From: Eivind Eklund Date: 2004-02-13T21:31:27+09:00 Subject: Re: Standard libraries On Fri, Feb 13, 2004 at 03:14:49PM +0900, NAKAMURA, Hiroshi wrote: > Hi, > > > From: "Gavin Sinclair" > > 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.