external snippets

[Jonathan Gibbons]

Anna,

Separate from whether you use `class` or `file` to identify the snippet, 
there are two locations in which you can put the files.

1. In a subdirectory named `snippet-files` of the package that 
references the snippet. In this case, you do _not_ need a 
`--snippet-path` option. In your example, this would be 
`src/main/java/p/snippet-files/Snippet.java`.  The use of a 
`snippet-files` dierctory is intended to be similar to `doc-files` to 
provide images or additional text files for documentation.

2. In an arbitrary directory (hierarchy) of your choice that is 
specified on the `--snippet-path` option. That is a path similar to a 
source path, and can contain multiple directories separated by the 
standard path separator character, if you so choose.

In your example, while it is not wrong to use `src/main/snippet-files`, 
you are relying on option #2 above, which is why you need the 
`--snippet-path` option.

-- Jon


On 2/23/22 4:03 AM, Anna Kozlova wrote:
> Hi folks,
>
> I try to support external snippets in IntelliJ. As far as I understand 
> this part of JEP 413
>
>     The location of the external code can be specified either by class
>     name, using the class attribute, or by a short relative file path,
>     using the file attribute. In either case the file can be placed in
>     a package hierarchy rooted in a snippet-files subdirectory of the
>     directory containing the source code with the {@snippet ...} tag. 
>
>
> I should be able to put snippet files somewhere near my code and the 
> javadoc tool would find them. Unfortunately, I failed to generate 
> javadoc unless I specify explicitly `--snippet-path`.
>
> I tried e.g. the following structure
> |└── src └── main ├── java │ └── p │ └── Main.java └── snippet-files 
> ├── p │ └── Snippet.java|
> Is this structure correct? Or should this `snippet-files` directory be 
> explicitly added as `--snippet-path ` by the IDE/build tool and I just 
> misread the JEP?
>
> Thank you,
> Anna
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20220321/9ed67765/attachment-0001.htm>