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

[Hannes Wallnöfer]

On Wed, 24 May 2023 20:15:45 GMT, Jonathan Gibbons <jjg 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}`

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