On Nov 25, 2011, at 3:49 AM, Luc Maisonobe <[email protected]> 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: [email protected]
>> For additional commands, e-mail: [email protected]
>>
>
>
> ---------------------------------------------------------------------
> 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]
