RFR: JDK-8292157: Incorrect error: "block element not allowed within inline element <a>"

[Jonathan Gibbons]

On Mon, 15 May 2023 14:43:15 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a change to downgrade from error to warning if the label of a `<a>` element or reference tag contains an HTML block element. Before HTML 5, elements were clearly divided into block and inline elements, and the latter were not allowed to contain the former. 
> 
> With HTML5, the division between block and inline elements is delegated to CSS, and although elements have default styles, styles can be freely customized by the author. This applies especially true for the `<a>` element which is commonly used both with inline and block layout. That was the rationale for downgrading from error to warning for the `<a>` element only. See the JBS issue comments for details and references.
> 
> The error message for the warning was enhanced to refer to the default style for the `<a>` element.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 80:

> 78: dc.tag.not.allowed = element not allowed in documentation comments: <{0}>
> 79: dc.tag.not.allowed.inline.element = block element not allowed within inline element <{1}>: {0}
> 80: dc.tag.not.allowed.element.default.style = block element not allowed within element <{1}> with default style: {0}

Is it possible to improve the wording?

As written, it is ambiguous/confusing: it seems like `{0}` is the default style, which I don't think is what you intend.
Also, inconsistent pointy brackets `<{1}>` but just `{0}`

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13990#discussion_r1204716808