Le 25/11/2011 08:13, Sébastien Brisard a écrit : > Hi, > here are a few questions about the implicit rules in use in CM for > formatting Javadoc comments, that I've wanted to post for a long time. > Since I'm now reviewing other people's patches, I think it's high time > to clear these questions up. If I'm not mistaken, > (1) every @param tag should start with a capital letter and end with a period > (2) every @return tag should end with a period > When I first submitted a patch (and it was corrected accordingly), I > was a little surprised, since it is in contradiction with conventions > [1] which I (and obviously, others) was used to > (3) Regarding @param tags: "The description begins with a lowercase > letter if it is a phrase (contains no verb), or an uppercase letter if > it is a sentence. End the phrase with a period only if another phrase > or sentence follows it." > (4) Regarding @return tags: "Use the same capitalization and > punctuation as you used in @param." > > I'm not saying these conventions are good/bad. However, they are > consistent with automatic tags (eg "Specified by", which do *not* end > with a period). Besides, I think rules (1) and (2) are not > consistently enforced throughout CM (to take but one example: I > constantly find myself reverting to my old habits...) and so I'm > reluctant to correct other people's work to try and comply with rules > I'm not absolutely sure everyone agrees about. > > I think it would be nice if everyone who is particularly attached to > an unstated rule just states it. We could then gather all those rules
As far as I am concerned, I use neither upper case nor period for @param and @return. I think Gilles does, so clearly there is no agreed upon convention. It seems really a detail to me (your mileage may vary), the content of the javadoc being far more important than its form. Luc > in the Developers resources section of the website (I can do that, > please just write up the list in this thread). This would allow us, > and others, to refer to this document in order to ensure homogeneity > throughout the whole library. > > What do you think? Best regards, > Sébastien > > [1] > http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
