[Checkers] Numbering in Javadoc comments
mernst at csail.mit.edu
Tue Jun 10 01:18:27 EDT 2008
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:
<li>the java.lang.Class class
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
// 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.
More information about the checkers