[External] : Re: external snippets
Jonathan Gibbons
jonathan.gibbons at oracle.com
Thu Mar 24 01:23:32 UTC 2022
Anna,
Maybe it was a typo but that command does not correspond to the file
layout you described earlier. The command is missing the `main/java/` part.
I don't know what `project_classpath` is in your case. If it is just the
(output) classes directory, you might try adding a sourcepath option,
which would be something like either `-sourcepath project_name/src` or
`-sourcepath project_name/src/main/java` depending on your layout.
I'll set up locally an environment that tries to mimic your layout, and
send you a confirmed command. If it is the `-sourcepath` issue, that
requirement needs to be added to the documentation.
-- Jon
On 3/23/22 1:02 PM, Anna Kozlova wrote:
> 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/177456d3/attachment-0001.htm>
More information about the javadoc-dev
mailing list