[External] : Re: external snippets

[Jonathan Gibbons]

Anna,

For javadoc itself, the intent is that you should not need to do 
anything else to have javadoc detect the `snippet-files` directory and 
to incorporate the content into the documentation.  You can verify that 
by manually running a javadoc command on the example files you have set up.

However, in the context of an IDE, it is important that the IDE should 
recognize the `snippet-files` directory (and other non-identifier 
directories) as not being part of the overall package structure. In 
other words,

1) when the IDE is analyzing the code in src/main/java, and when passing 
files to `javac` and `javadoc` it should not include files from any 
directory that is not part of the package hierarchy ... i.e. it should 
not include files from `snippet-files` and `doc-files` directories.
Note that javadoc will still look for and scan the `snippet-files` 
subdirectory in the package for any doc comments that use snippets.

2) separately, to allow a user to work on snippet files, an IDE 
could/should recognize the `snippet-files` directory as an independent 
(nested) package root.

-- Jon


On 3/22/22 12:07 PM, Anna Kozlova wrote:
> Hi Jonathan,
>
> how should IDE(A) pass the content of `snippet-files` to the 
> javadoc, javac, etc? I hope I'll be able to fix that so users will be 
> able to use the simple way of defining external snippets.
> Thanks
> Anna
>
> On Tue, Mar 22, 2022 at 3:31 PM Jonathan Gibbons 
> <jonathan.gibbons at oracle.com> wrote:
>
>     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/20220323/e165607e/attachment-0001.htm>