On Wed, 24 May 2023 20:15:45 GMT, Jonathan Gibbons <j...@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}`
Would the following be better?
block element <{0}> not allowed within element <{1}> with default style
I found inconsistent use of angle brackets in several other messages in that
file. Attempting to fix that causes a lot of breaking doclint tests, not sure
if it is worth doing that as part of this change.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/13990#discussion_r1213141539
