[External] : Re: external snippets

[Anna Kozlova]

Jonathan,

IDEA runs javadoc tool as following
`javadoc -d output -classpath project_classpath
project_name/src/p/Main.java`. I can change this if I would understand what
should be placed instead.

I am sorry for not being able to understand myself

Thanks,
Anna

On Wed, Mar 23, 2022 at 3:48 PM Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

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