commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [math] javadoc implicit formatting rules
Date Fri, 25 Nov 2011 10:51:01 GMT




On Nov 25, 2011, at 3:49 AM, Luc Maisonobe <Luc.Maisonobe@free.fr> wrote:

> 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.
> 

+100

Not worth arguing about.  Key is content.  Following standard conventions is better, but I
can live with the nonstandard stuff as long as the content is correct and complete.

Phil
> 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
> 

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


Mime
View raw message