commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gary Gregory" <ggreg...@seagullsoftware.com>
Subject RE: [io] svn commit: r491668 - /jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
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,
Gary

> -----Original Message-----
> From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
> Sent: Monday, January 01, 2007 5:36 PM
> To: Jakarta Commons Developers List
> Subject: Re: [io] svn commit: r491668 -
>
/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtil
s.
> 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
if
> 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
> 
> 
> ggregory@apache.org wrote:
> > Author: ggregory
> > Date: Mon Jan  1 14:45:49 2007
> > New Revision: 491668
> >
> > URL: http://svn.apache.org/viewvc?view=rev&rev=491668
> > Log:
> > Add missing Javadoc tags. Use "null" is code format
(<code>null</code>)
> >
> 
> > -     * @param file  the file to open for input, not null
> > +     * @param file  the file to open for input, must not be
<code>null</code>
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 


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


Mime
View raw message