I'm trying to significantly reduce the number of error messages from the ant doc command, so that the genuine errors can be seen and dealt with. Currently, for example, there's an unclosed bold tag over a lot of an online Javadoc page. (It seems to have been fixed in the original files now though.)

This isn't finished yet; I'd like some advice. This first commit was just running GenerateDescriptions.py with some patching/manual editing of files where it was broken. This was so that if I needed to modify and rerun the script or XMLs later, the later commits' diffs wouldn't contain ordinary updates to XML files.

The second commit fixes most of the errors except those in the HTML and syntax categories of Javadoc's Doc-lint tool, and suppresses the production of those messages by the Javadoc tool. It also makes the @usage and @brief tags display in the proper Javadoc, since that was an option I had when stopping them from being errors; I can hide them if preferred.

This just leaves the syntax errors. As far as I can tell, there's no way to stop Javadoc moaning about <br /> but keep getting the useful messages about unclosed tags and other real errors. And there are loads of messages about <br />, making Javadoc's output almost unreadable if you don't suppress them. So: can I

• modify all the XML files to make them say <br> as preferred?
• modify the script to convert <br /> to <br>?
• or just leave it alone and keep all syntax errors suppressed?

I'm asking because I don't know what else uses those files and how strict their XML needs to be. I'd also need to wrap code samples in the XMLs in {@code } tags where they contain angle brackets (which escapes them) to avoid filling the doc comments in the .java files with <<=; can all other users of the XML files handle that sort of Javadoc syntax?