From: "NAKAMURA, Hiroshi" <nahi@...>
Date: 2004-02-13T13:32:34+09:00
Subject: Re: Standard libraries

Hi,

> From: "Gavin Sinclair" <gsinclair@soyabean.com.au>
> Sent: Thursday, February 12, 2004 11:59 PM

> > Anyway, on of Ruby's features is a lack of static typing.  Unfortunately, this
> > makes it impossible for a tool to determine the type of arguments and
> > methods, so this shifts the burden of documentation on the developer.

> > Basically, the code duplication that Hiroshi is complaining about is required
> > for good documentation, because there's no other way of extracting 
> > constraints information from the source code, except by reading it by hand.

Kind of agree-ed.  Yes, there's no other way.  Regards to
"good documentation", I don't think duplicated documentation never
could be good.  May be wrong.  May be old.  Source mean everything.

> > I really don't want to force users to understand all 4,600 lines of REXML
> > just to use it; that defeats the purpose of it.

I think public API signature and it's source should be enough
descriptive for private implementation.

For example,

  def CSV.open(filename, mode, col_sep = ?,, row_sep = nil, &block)
    if mode == 'r' or mode == 'rb'
      open_reader(filename, col_sep, row_sep, &block)
    elsif mode == 'w' or mode == 'wb'
      open_writer(filename, col_sep, row_sep, &block)
    else
      raise ArgumentError.new("'mode' must be 'r', 'rb', 'w', or 'wb'")
    end
  end

With this API, "block" is not desctiptive.  I should only add
comments;

  # block is yielded with a CSV::Writer when 'w' or 'wb'
  # block is yielded with CSV::Row-s when 'r' or 'rb'

Or, change this ugly API. :-)  Current 50 lines long comment seems
to be duplicated for me (example exists in sample/csv/*).

> Method documentation is neccesary to help people understand the code -
> I agree.

I hope you allow me, I don't agree.  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?

  def CSV.open(filename, mode, col_sep = ?,, row_sep = nil, &block)

    # block is yielded with a CSV::Writer when 'w' or 'wb'
    # block is yielded with CSV::Row-s when 'r' or 'rb'
    if mode == 'r' or mode == 'rb'
      open_reader(filename, col_sep, row_sep, &block)
    elsif mode == 'w' or mode == 'wb'
      open_writer(filename, col_sep, row_sep, &block)
    else
      raise ArgumentError.new("'mode' must be 'r', 'rb', 'w', or 'wb'")
    end
  end

may not be enough.

  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?

# Note: I wrote all comment in above examples.  First see
# rdoc, I tried the new culture...  But I cannot live with it.

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

Regards,
// NaHi