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 phil.steitz@gmail.com
 designates 209.85.161.171 as permitted sender)
Subject: Re: [math] javadoc implicit formatting rules
References: 
 <CAGRH7HppBKqbOAcFkkKqmZB56h4OrFWLyQzCG+gGm04_c8RgUQ@mail.gmail.com>
From: Phil Steitz <phil.steitz@gmail.com>
Content-Type: text/plain;
	charset=utf-8
In-Reply-To: 
 <CAGRH7HppBKqbOAcFkkKqmZB56h4OrFWLyQzCG+gGm04_c8RgUQ@mail.gmail.com>
Message-Id: <A35C7AD0-D9B0-44F5-AA25-2C723FD2DA1E@gmail.com>
Date: Fri, 25 Nov 2011 06:09:52 -0500
To: Commons Developers List <dev@commons.apache.org>
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (1.0)

One more point on this.  "Consistency" as some sort of independent goal by i=
tself 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 d=
oco design contributes to these goals, great.  But arcane rules or excessive=
ly complicated APIs that make it harder for people to use the software and g=
et involved are to be avoided.

Phil

On Nov 25, 2011, at 2:13 AM, S=C3=A9bastien Brisard <sebastien.brisard@m4x.o=
rg> 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 per=
iod
> (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."
>=20
> 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.
>=20
> 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.
>=20
> What do you think? Best regards,
> S=C3=A9bastien
>=20
> [1] http://www.oracle.com/technetwork/java/javase/documentation/index-1378=
68.html#tag
>=20
>=20
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>=20

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