Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (nike.apache.org: domain of
 SRS0=Qlcq=6H=m4x.org=sebastien.brisard@bounces.m4x.org designates
 129.104.30.34 as permitted sender)
MIME-Version: 1.0
Date: Fri, 25 Nov 2011 08:13:06 +0100
Message-ID: 
 <CAGRH7HppBKqbOAcFkkKqmZB56h4OrFWLyQzCG+gGm04_c8RgUQ@mail.gmail.com>
Subject: [math] javadoc implicit formatting rules
From: =?ISO-8859-1?Q?S=E9bastien_Brisard?= <sebastien.brisard@m4x.org>
To: Commons Developers List <dev@commons.apache.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

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 peri=
od
(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=E9bastien

[1] http://www.oracle.com/technetwork/java/javase/documentation/index-13786=
8.html#tag


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