[Bug classpath/22801] Comments should use XHTML-1.0-Strict and prefer meaningful markup

[gcc-bugzilla at gcc dot gnu dot org]

All javadoc comments should comply with XHTML-1.0-Strict.  In addition,
structural markup should be preferred over presentational markup.  For example,
instead of <b> the tag <em> or <strong> should be used. If decorations (like
colors, font sizes etc.) are required, they should be added using CSS.

Furthermore, a set of standard CSS classes should be established which should
then be consistently used in all comments.  For instance, Java code examples
could always be put inside a <div class="java-code-example"> tag.

Rationale: when all comments use meaningful XHTML-1.0-Strict markup only, the
API documentation can be generated in XHTML-1.0-Strict format, and it can be
converted properly to non-HTML formats like DocBook.

At a later point, gjdoc may help with the process of converting to XHTML by
emitting warnings when a comment uses markup other than valid XHTML-1.0-Strict.

See also:
http://www.w3.org/TR/xhtml1/
http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=22801