external snippets

[Anna Kozlova]

Hi Jonathan,
thank you! Unfortunately (1) doesn't work for me, what I get with the last
available jdk 18:

Standard Doclet version 18+36-2087
Building tree for all the packages and classes...
Generating project_name/output/p/Main.html...
project_name/src/p/Main.java:8: error: File not found: ShowOptional.java
 * {@snippet file="ShowOptional.java" region="example"}


where I have code from the JSR sample
package p;

/**
 * {@snippet file="ShowOptional.java" region="example"}
 */
public class Main {}

Can it be that I need to pass javadoc tool, something which I am not aware of?

Thanks,
Anna


On Mon, Mar 21, 2022 at 3:59 PM Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> 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/5d999ef1/attachment-0001.htm>