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