[External] : Re: external snippets
Jonathan Gibbons
jonathan.gibbons at oracle.com
Thu Mar 24 14:39:56 UTC 2022
Anna,
Thanks for the update and for your efforts to support snippets within
IDEA; I'm pleased you finally got it working.
FWIW, there is a new Programmers Guide for snippets available with JDK 18.
https://docs.oracle.com/en/java/javase/18/code-snippet/index.html
-- Jon
On 3/24/22 12:16 AM, Anna Kozlova wrote:
> Jonathan,
>
> thanks, it works with the "-sourcepath" option!
>
> Thanks again,
> Anna
>
> P.S. It was a typo in the path, I removed too much from my real
> absolute path, sorry about that
>
> On Thu, Mar 24, 2022 at 2:23 AM Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
>
> 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/20220324/cda24317/attachment-0001.htm>
More information about the javadoc-dev
mailing list