On 26 July 2013 14:44, roger riggs <roger.ri...@oracle.com> 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: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html Nor the FAQ: http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html 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. " http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html (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. Stephen
