[External] : Re: external snippets

[Jonathan Gibbons]

Anna,

What is the layout for the files you are using?

-- Jon


On 3/21/22 10:31 AM, Anna Kozlova wrote:
> 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/635beff4/attachment.htm>