commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gary Gregory" <>
Subject RE: [io] svn commit: r491668 - /jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/
Date Tue, 02 Jan 2007 03:00:46 GMT
Hi All:

Interesting and I do see your POV. IMO, it also depends on what tools
you use do to your work. I use the Eclipse Javadoc view which presents
the Javadoc comment in a formatted HTML view. I never bother to use the
source of Javadocs to understand what the comments "say" as there
usually is too much meta information, {@links} and {@whatnots}, to
really make reading easy.

I guess it comes down to how you want to present each [project] to the
outside world. Since I find the Sun JRE Javadoc usually pretty poor, in
general, I do like to make my Java comments more technically detailed
and prettier.

Feel free to replace all <code>null</code> with null ;)

Thank you,

> -----Original Message-----
> From: Stephen Colebourne []
> Sent: Monday, January 01, 2007 5:36 PM
> To: Jakarta Commons Developers List
> Subject: Re: [io] svn commit: r491668 -
> java
> I'll be honest and say I dislike the convention of using <code> for
> null, as as such I'm not greatly enthused by this change. I'd prefer
> no more files were changed.
> This comes down to my basic tenet that javadoc is for developers to
> read, and it is *frequently* read as source code, not as an HTML page.
> Adding the <code> makes its *much* more difficult for someone to read
> the text. And its the text that matters.
> Just read the two lines below and decide which is easier to read and
> extract meaning from.
> In addition, since every Java programmer knows that null is a reserved
> word, I really don't see what is gained by highlighting it.
> Stephen
> wrote:
> > Author: ggregory
> > Date: Mon Jan  1 14:45:49 2007
> > New Revision: 491668
> >
> > URL:
> > Log:
> > Add missing Javadoc tags. Use "null" is code format
> >
> > -     * @param file  the file to open for input, not null
> > +     * @param file  the file to open for input, must not be
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message