[Checkers] Numbering in Javadoc comments

[Michael Ernst]

Telmo-

I noticed that revision r2707 made a variety of improvements (thanks), and
also changed a number of ASCII numbered lists to HTML <ul>...<li>...</ul>.

In general, that is the right thing to do, but in this particular case I'd
asked for the ASCII numbering, as an exception to the rule.  Here is text
from my message of "Sun, 1 Jun 2008 19:40:12 +0200":


  I have a suggestion regarding how to make the helpful comments in the
  checkers/visitors/factories even more helpful.  Currently, they are
  organized as HTML lists:
    <ul>
      ...
      <li>the java.lang.Class class
      <li>enum classes
      ...
    </ul>

  Instead of using automatic numbering, number the clauses by hand:
    ...
    4. the java.lang.Class class
    5. enum classes
    ...
  If there were multiple HTML lists in one Javadoc, number sequentially
  rather than starting subsequent lists from 1 again.

  Then, wherever in the class that a particular rule is implemented, add a
  Java comment:
    ...
    // Case 4. the java.lang.Class class
    ...
    // Case 5. enum classes

  This will make it much easier to understand the purpose of each part of the
  code, and to see whether anything has been omitted from the documentation
  or from the code.


So, if you could make this change before the code review (that is, by the
morning of Monday, June 16), that would be helpful.

This is especially important because we want the distributed checkers to be
models of comprehensibility and good style for others to copy from.

Thanks!
                    -Mike