From: Dave Thomas <dave@...>
Date: 2004-02-13T14:10:48+09:00
Subject: Re: Standard libraries


On Feb 12, 2004, at 22:32, NAKAMURA, Hiroshi wrote:
>   class Row < Array
>     # SYNOPSIS
>     #   CSV::Row#to_a
>     #
>     # RETURNS
>     #   An Array of String.
>     #
>     # DESCRIPTION
>     #   Convert CSV::Cell to String.  Null is converted to nil.
>     #
>     def to_a
>       self.collect { |cell| cell.is_null ? nil : cell.data }
>     end
>     ...
>   end
>
> Is this comment needed?
>

I don't think all of it is. I might document it as

    # Return this row as an Array containing Strings or +nil+
    def to_a
      ...
    end

I honestly think there's a balance between too much and too little 
documentation. Too much gets in the way, but too little makes the 
learning curve steeper than it needs to be.

The Pickaxe didn't document anything that wasn't already in the Ruby 
source code. But it still made a fairly big difference to people coming 
to the language for the first time to have the book available.


Cheers

Dave