Re: Standard libraries

On Fri, Feb 13, 2004 at 03:14:49PM +0900, NAKAMURA, Hiroshi wrote:
> Hi,
> 
> > From: "Gavin Sinclair" <[e-mail]>
> > Sent: Friday, February 13, 2004 2:54 PM
> 
> > >> 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.
> 
> Thanks.
> 
> From my experience, for good development, library user
> should read the source instead of per method document
> (and library developer should aware of it).

My experience partially differs.  Yes, the user should be able to read
the library code.  However, this is something that should not be done as
the generic reference for the code - it should be done when something is
unclear (things are not behaving the way I expected from the docs.)

There is also a significant difference between documentation in the form
of text and documentation in the form of code:
- Text documents what the author intended the code to do.
- Code documents what the code *does*.

I believe both of these as important to know for using a codebase.

With regards to duplication etc: There are several ways to decrease
duplication compared to the example you originally came with, even
containing the exact same information.  If we (as in any member of the
community) run into problems with duplication due to docs, I suggest we
try to look at what gets duplicated and how we can avoid that.

Example: Parameter name duplication can be removed by associating the
comments directly with the parameters, for instance (ie, splitting
parameters into one per line, add a comment to the end of line, have
rdoc extract these comments.)

Eivind.