Invalid "self-closing element not allowed" JavaDoc error

Stephen Colebourne scolebourne at
Fri Jul 26 15:44:06 UTC 2013

On 26 July 2013 14:44, roger riggs <roger.riggs at> wrote:
> The html subset that appears in javadoc comments does not exist in isolation
> or in a full browser context.
> It is deliberately limited and structured to work within a documentation
> framework
> defined by javadoc and supported by the javadoc stylesheet using HTML 4.01.

The Javadoc page doesn't seem to describe an HTML subset:
Nor the FAQ:

Ah, here we go:

"Comments are written in HTML - The text must be written in HTML, in
that they should use HTML entities and can use HTML tags. You can use
whichever version of HTML your browser supports; we have written the
standard doclet to generate HTML 3.2-compliant code elsewhere (outside
of the documentation comments) with the inclusion of cascading style
sheets and frames. (We preface each generated file with "HTML 4.0"
because of the frame sets.) "

"Use header tags carefully - When writing documentation comments for
members, it's best not to use HTML heading tags such as <H1> and <H2>,
because the Javadoc tool creates an entire structured document and
these structural tags might interfere with the formatting of the
generated document. However, it is fine to use these headings in class
and package comments to provide your own structure. "
(the latest version linked from the JavaSE page)

So, it would seem that doclint is enforcing something that this spec
does not require - "You can use whichever version of HTML your browser
supports" - and no more than a weak warning against h1 and h2.

This now looks like doclint is enforcing somthing that doesn't exist,
close to being backwards incompatible. This looks more and more wrong
to me.


More information about the core-libs-dev mailing list