On Feb 13, 2004, at 4:16 AM, Sean E. Russell wrote:

> On Friday 13 February 2004 01:14, NAKAMURA, Hiroshi wrote:
>> From my experience, for good development, library user
>> should read the source instead of per method document
>> (and library developer should aware of it).
>
> In my experience, I'd say that this means you've either (a) never used 
> a
> library that had good documentation, or (b) never used a large 
> library, or a
> large number of libraries in one project.
>

NaHi's soap4r is a good example.  It's a big library.  In most general 
cases a user would only need to be familiar with a few methods so maybe 
only those need careful inline documentation.  But also the overall 
structure of the library, introduction and examples are maybe best 
described in a README type document.  Even if such documentation is at 
the head of the source, it seems necessary to have a README ready for 
people download the tarball.

What I'm doing with an extension I'm trying to write today is to use 
rdoc to weave a README.en from the makefile so that someone who just 
downloads it will have something to read immediately.

But there's also the problem of much of this style of documentation not 
making it into ri.  For instance, it would be great if 'ri rdoc' 
produced an overview of rdoc, or if 'ri soap4r' did likewise.  It'd be 
even better if 'ri -k soap' produced a list of soap facilities in ruby.