On Thu, Jan 13, 2011 at 10:34:00AM -0500, Phil Steitz wrote:
>
>
>
>
> On Jan 13, 2011, at 7:21 AM, Gilles Sadowski <gil...@harfang.homelinux.org>
> wrote:
>
> > Hi.
> >
> >> [...]
> >>>
> >>>> A couple of areas where we have slipped a bit over the years that I
> >>>> would rather apply energy to than formatting are the following (from
> >>>> the Developers' guide):
> >>>>
> >>>> # All component contracts must be fully specified in the javadoc
> >>>> class, interface or method comments, including specification of
> >>>> acceptable ranges of values, exceptions or special return values.
> >>>> # External references or full statements of definitions for all
> >>>> mathematical terms used in component documentation must be provided.
> >>>> # Implementations should use standard algorithms and references or
> >>>> full descriptions of all algorithms should be provided.
> >>>> # Additions and enhancements should include updates to the User Guide.
> >>>
> >>> This is all OK, of course. But what I had in mind is more of a "cheat
> >>> sheet", that can be checked easily by the developer (and maybe partly by
> >>> CheckStyle?) so that we can be sure that the doc is both complete and a
> >>> pleasant read (which, I'm convinced, is helped by a consistent form).
> >>>
> >>
> >> Your ideas for modifying the Sun standard are interesting.
> >> Personally, I prefer to stick with the standard, for the reason that
> >> others have stated that it is easier for contributors to follow and
> >> creates less work modifying patches (and new code) to comply. As I
> >> said above, I would much rather see effort go into filling in the gaps
> >> and clarifying the imprecision in the content of the javadoc (both
> >> existing and that which comes with patches) than to "standardizing"
> >> format. Lets see what others in the community think.
> >
> > So, together, we say that both formatting and contents need improvement.
> > Since they are not contradicting goals, both can be achieved.
>
> Yes, though I don't see big problems with formatting and I don't see the need
> - and in fact see reasons not to - depart from the established standard or
> add more requirements that contributors need to follow.
There are no big problems, just a lot of small ones (e.g. using a keywords
like "null" without writing it as "{@code null}" and some comments being
complete sentences while others aren't).
If this is not important (again, I'm not saying it should be high-priority),
then I'd strongly suggest to remove the "trailing white space" rule from
CheckStyle because that one should be orders of magnitude less important...
> >
> > We can diverge as to their respective priority, as far as the upgrade of
> > existing code is concerned.
> > But what I'm suggesting is to lay out simple and concise rules (by
> > extracting the relevant part of the "standard", if need be) so that from now
> > on, the changes (code and doc) are provided in the best possible form.
> >
> My personal view is that the standard is fine as is. If others agree with
> your suggested changes and are willing to sign up for the associated
> maintenance, we can agree on and make changes to the Developer Guide.
The standard may be fine; it's just not applied everywhere in the doc,
that's the point: Whatever the rules, it should be easy to check a block of
Javadoc comment against the cheat sheet and to conclude that "Rule 1, 3 and
9 are violated."
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
