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.gibb...@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.gibb...@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.gibb...@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
