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 11:09:52 GMT
One more point on this.  "Consistency" as some sort of independent goal by itself has no place
in open source software.  We need to keep our eyes on the prize, which is making it easy for
users to understand and use the software and for volunteers to get involved.  To the extent
that consistent API and doco design contributes to these goals, great.  But arcane rules or
excessively complicated APIs that make it harder for people to use the software and get involved
are to be avoided.

Phil

On Nov 25, 2011, at 2:13 AM, S├ębastien Brisard <sebastien.brisard@m4x.org> wrote:

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