[External] : Re: external snippets

[Jonathan Gibbons]

Anna,

That is the intended structure, but my experience has been that existing 
releases of the IDE incorrectly pass the contents of directories like 
`snippet-files` as source files when compiling the primary packages and 
classes, meaning `p/Main.java`. This applies to any analysis of the 
files in the package/class hierarchy, including `javac`, `javadoc`, and 
tools like IDE that examine source code,

Note that `snippet-files` is not a valid identifier, and so files in the 
`snippet-files` directory cannot be considered part of the package 
hierarchy rooted at `src/main/java`.    That is true for any 
sub-directory that is not named with a valid Java identifier.   Until 
this aspect of the IDE is addressed, you cannot use option 1 as I 
described earlier (using the local snippet-files subdirectory) and so 
you must use option 2 ( a separate package/class hierarchy, with the 
`-snippet-path` option).

-- Jon

On 3/22/22 6:21 AM, Anna Kozlova wrote:
> Hi Jonathan,
> I have this structure:
>
> └── src
>
> └── main
>
> ├── java
>
> └── p
>
> └── Main.java
>
> |── snippet-files
>
> └── ShowOptional.java
>
>
> I think that IDE passes wrong parameters to the javadoc tool though I 
> have no idea what should be changed. E.g. if I try to generate javadoc 
> for the whole 'p' directory, snippet-files are passed as [sources] but 
> I have still the same error. What should be on the command line?
>
>
> Thanks,
>
> Anna
>
>
> On Mon, Mar 21, 2022 at 7:25 PM Jonathan Gibbons 
> <jonathan.gibbons at oracle.com> wrote:
>
>     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/20220322/3a7913ee/attachment.htm>