[External] : Re: external snippets

[Anna Kozlova]

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