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