RFR: 8321500: javadoc rejects '@' in multi-line attribute value

[Jonathan Gibbons]

On Tue, 15 Oct 2024 10:41:43 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review the removal of code in `DocCommentParser` that created an error when encountering a spurious "@" character in an HTML attribute value after a line break. 
> 
> The removed code (which was added in its current form in 2012) seemed to assume that such a "@" character was part of a block tag and therefore an indication of an unclosed attribute value. However, both line breaks and "@" are valid characters in HTML attributes. Note that valid content for HTML attributes in `DocCommentParser` is [text and entities as per HTML5][html5-attributes] as well as JavaDoc inline tags, but not block tags.
> 
> [html5-attributes]: https://html.spec.whatwg.org/multipage/syntax.html#syntax-attribute-value
> 
> The change adds two doctree tests, one to make sure HTML attributes with mixed values (text, line breaks, entities, inline tags, "@") are parsed correctly, and a second one to make sure actual unclosed attribute values are still recognized as errors.

The original behavior for javadoc (I hesitate to call it a spec) was that any and every occurrence at the beginning of a line (after any leading whitespace) was the beginning of a block tag. This predated the introduction of `DocCommentParser` and was related to (not sure which was cause or effect) the way that the comment was "parsed" by breaking into an initial description followed by block tags, almost completely ignoring any HTML content within those sections.

That behavior was honored when `DocCommentParser` was introduced, and remained in place until it was modified to allow leading `@` characters inside inline tags, to work around the "annotation problem" in code samples, whether using `{@code}` or `{@snippet}`.

I don't disagree that this change might be a good one, but it is a deliberate change in documented and/or long-standing behavior, and so needs a CSR and probably a spec update somewhere.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/21520#issuecomment-2414489475