Re: [io] svn commit: r491668 - /jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java

[Stephen Colebourne <sc...@btopenworld.com>]

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

RE: [io] svn commit: r491668 - /jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java

[Gary Gregory <gg...@seagullsoftware.com>]

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