java: javadoc: Consider clarifying “containing only the aligned leading asterisk”
oliviercailloux opened this issue · comments
About Javadoc, the GJSG states: “One blank line—that is, a line containing only the aligned leading asterisk (*)—appears between paragraphs, and before the group of block tags if present.”
Is the intent to prohibit a space after the asterisk? I thought not as the space does not hurt visually and is useful (as reported here), but others interpret this differently.
Please consider clarifying, for example by rewording to “a line containing only the aligned leading asterisk (*) optionally followed by a single space character”, if this is the intent.
the intent is to not have trailing whitespace. many editors & formatters will flag & delete it automatically.
In Google's internal version of this style guide, there is a section on issues that do not deserve to be commented on in code reviews. Trailing whitespace is the very first one. So I think we could consider that the intent is that there really is just an asterisk with no following space, but if there is following space then that is not worth commenting about. The internal guide does also say "It is reasonable to ask the reviewee to check their editor configuration, but don't point out specific violations." (Referring to this and also things like whether there is a newline at the end of the last line.)
I have to say that I'm not really convinced by the argument that a space after the asterisk is useful because you might conceivably be adding new comment text there. It isn't hard to type a space when you need one.