commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luc Maisonobe <Luc.Maison...@free.fr>
Subject Re: [math] javadoc implicit formatting rules
Date Fri, 25 Nov 2011 08:49:03 GMT
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: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message