Thank you for your email. I think it is the first piece of feedback we have
received on the {@snippet} section of the Documentation Comment Specification
for the Standard Doclet. So it is quite likely that this section has
deficiencies to be fixed. I'll reply in detail shortly. This email is to
acknowledge that we have received your feedback.
-Pavel
> On 15 Mar 2023, at 21:14, Tagir Valeev <[email protected]> wrote:
>
> Hello!
>
> I'm working on @snippet support improvement in IntelliJ IDEA. I'm using the
> following page as the primary source of information:
> https://docs.oracle.com/en/java/javase/19/docs/specs/javadoc/doc-comment-spec.html#snippet
>
> Unfortunately, it leaves many questions about how the snippets should be
> parsed and rendered. Here's my feedback, hopefully it could be helpful.
>
> 1. Attribute value syntax. The spec says "An attribute value may be an
> identifier, unsigned integer, or enclosed in either single or double quote
> characters; no escape characters are supported". I assume that {@snippet
> class=pkg.Class} is a malformed tag, as pkg.Class is not an identifier and
> not quoted. Nevertheless, it's parsed by the javadoc tool and displayed, as
> if it were {@snippet class="pkg.Class"}. Similarly {@snippet
> file=pkg/Class.java} also works, while according to the spec it should not.
> Is it an implementation problem (implementation is more permissive than
> required by spec) or a spec problem? If such tag should be accepted, could
> you specify which non-identifier symbols exactly are allowed in unquoted
> values?
>
> 2. "region" attribute. It's not explicitly specified that such an attribute
> exists. One can only guess from existing samples and javadoc tool
> implementation. Only "id", "lang", "class", and "file" attributes are
> mentioned in the specification. It would be nice to specify the "region"
> attribute as well.
>
> 3. "class" attribute. It's specified that "The location of the external code
> can be specified either by class name". However, in fact it's not the class
> name. If I create a file snippet-files/Xyz.java and declare a class named
> "class Abc {}" there, I should refer to it with {@snippet class=Xyz}, rather
> than {@snippet class=Abc}. It looks to me that the class attribute is just an
> alternative to a file attribute, which can be constructed from class using
> `classAttribute.replace('.', '/')+".java"`. It does not check whether the
> class with a given name and package statement actually appears in a given
> file. It would be nice to clarify this part of the spec.
>
> 4. Markup tags placement. It's specified: "They are placed in // comments (or
> the equivalent in other languages or formats)". To me, it's quite a vague
> statement. Apparently, parser cannot understand every single existing file
> format in the world, so it may have no idea how comments are represented in
> the target file format. Moreover, target file format may have no formal
> specification. For example, if we have external snippet with .txt extension,
> which kind of comment prefix should we use to define regions? I tried
>
> outside
> # @start region="hello"
> mytest
> # @end
>
> The javadoc tool fails to find the region in this case. But I can argue that
> # represents a comment line in my text files. I strongly feel that this part
> should be specified more precisely: either list all possible preceding
> symbols, or provide another exact description about which preceding
> characters are recognized as comment start. Should the parser behavior
> actually depend on the language (specified by 'lang' attribute or file
> extension)?
>
> 5. Markup tag arguments format. It's not specified completely. There is a
> sample `@start region=name` which implies that "name=value" format is used
> for arguments, but it's completely unclear which characters are allowed,
> which are not, whether the quotation is supported, are there any escape
> characters, etc. This is especially important, as arguments may contain
> regular expressions which are known to contain non-trivial characters. One
> may guess that markup tag arguments are formatted exactly like snippet tag
> attributes, but it would be nice to specify this explicitly.
>
> 6. Whitespace rendering. While it's said that "Markup comments do not appear
> in the generated output", the spec does not say anything about preceding
> whitespace. E.g., consider the following snippet:
>
> /**
> * {@snippet lang=Java :
> * System.out.println(1);
> * // @replace substring=2 replacement=3:
> * System.out.println(2);
> * }
> */
>
> We exclude the // comment from the rendering. However, there are four spaces
> before it. Should they be rendered? The javadoc tool does not render them. It
> would be nice to specify this behavior.
>
> 7. Common indentation. It looks like the common indentation is stripped from
> the rendered snippet, similarly to text blocks. Is it an implementation
> detail or should be specified?
>
> 8. @highlight type. It's not specified which highlight type is used by
> default. Javadoc tool uses 'bold'. It would be nice to specify this
> explicitly. Also, it's said that "Valid type names are bold, italic, and
> highlighted". To me it means that any other type name should be reported as
> invalid. However, javadoc tool just ignores it. It's unclear to me from the
> spec whether it's possible to define custom CSS class names and use them here.
>
> 9. Link type. It's unclear to me how "linkplain" should differ from "link".
> It looks like, javadoc tool renders them in the same way, as the whole
> snippet is monospaced.
>
> Sorry if I'm missing some information.
>
> With best regards,
> Tagir Valeev.
>
>
