Re: Standard libraries

>> Method documentation is neccesary to help people understand the code -
>> I agree.
>
> I hope you allow me, I don't agree.

Of course I allow you :)  I'm curious what your reasons are.

> This should be a culture gap. If I
> want to soap/wsdl/xsd modules to be bundled with Ruby, I should accept
> the different culture.  If I can't accept it, I distribute
> it separately as before (I don't like inline document added to my
> source even if someone else maintains the document instead of me).
>
> How "complete" document is needed?

Inline documentation is required just to allow 'ri' to help users
understand the library.  Not detailed documentation of every private
method.

With soap/wsdl/xsd, I think an external document that gives the users a
good introduction and reference is the best.  Then if I run 'ri SOAP' and
get "See http://www.nahi.home.page.com/soap.html", I'll be happy.


>   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?

This is how I would comment it.

  class Row < Array
    #
    # Returns the strings contained in the row's cells.
    #
    def to_a
      self.collect { |cell| cell.is_null ? nil : cell.data }
    end
  end

Notice I avoid duplication.  You say "Returns an Array of String".  But
to_a *obviously* returns an array.  You name the method explicitly, but
there's no need.  You mention "Null is converted to nil", but that is
entirely predictable behaviour.  It's not unreasonable to document that,
though.

Notice that the single sentence I wrote as documentation is something that
is unlikely to change.


> And, all ext/* modules must be documented before the next stable
> release such as 1.8.2?  Who...

Don't get too carried away ;)  The proposed criteria for inclusion in the
standard library covered *new* additions.  I don't think Matz will throw
half the current library away before 1.8.2 :)

Anyway, I'm going to start on strscan soon, as the docs already exist
elsewhere.

Cheers,
Gavin