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
