Re: Standard libraries

Hi,

> From: "Gavin Sinclair" <[e-mail]>
> Sent: Thursday, February 12, 2004 1:32 PM

> >> > RDoc style is a must?  I don't like documentation buried within a
> >> source code (code duplication for me).
> >>
> >> RDoc is the standard way to document standard library files.  It's
> >> only code duplication if you put code in the comments :)
> >
> > Anyway, duplication of something I don't like to see/maintain.
> 
> I'm still not sure what you think is being duplicated.

For example, a documentation of current CSV.open is as follows.

  # SYNOPSIS
[snip]
  # ARGS
  #   filename: filename to open.
  #   mode: 'r' for read (parse)
  #         'w' for write (generate)
  #   row: an Array of cells which is a parsed line.
  #   writer: Created writer instance.  See CSV::Writer#<< and
  #     CSV::Writer#add_row to know how to generate CSV string.
  #
  # RETURNS
  #   reader: Create reader instance.  To get parse result, see
  #     CSV::Reader#each.
  #   writer: Created writer instance.  See CSV::Writer#<< and
  #     CSV::Writer#add_row to know how to generate CSV string.
  #
  # DESCRIPTION
  #   Open a CSV formatted file to read or write.
  #
  # EXAMPLE 1
[snip]
  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

When I want to do refactoring such as param name change
(filename -> file_name), or to change disabling 'wb' as a value,
I must change the code and the document, too.  It's not fun for me.

> >> Still with 'soap', the SOAP module should have enough documentation to
> >> show the user how to use it.  And they should get an idea of which
> >> classes are important to them, and which ones are not.
> >
> > I added many samples to show "how to use it" but it could not be
> > enough.  I thought I was going to write some simple document and
> > import libs to ruby's CVS.  But I have no plan to write it inline
> > to avoid the duplication.
> 
> If there is a document describing 'soap' somewhere on the Internet, then a
> few comments above the SOAP module and a link to the document would be
> sufficient for a user, wouldn't it?

Definitely, if it is not required that documenting responsibilities
of all public/important methods...

> But then again, are you maintaining ruby/lib/soap/* and 'soap4r'
> separately?  I would prefer to see just one package, with unit tests,
> samples, etc. rolled into the Ruby distribution.  But that's just a gut
> feel, not based on experience or qualifications.

Yes, separately.  src/lib/soap4r contains aggressive changes.
One day I fix the spec, release it, wait bug reports for a few days,
and copies it into ruby/{lib,sample,test}/{soap,wsdl,xsd}/*.

Regards,
// NaHi