On Mon, 15 May 2023 14:43:15 GMT, Hannes Wallnöfer <hann...@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
