Re: CVS commit: src

[Mindaugas Rasiukevicius <rmind%netbsd.org@localhost>]

yamt%mwd.biglobe.ne.jp@localhost (YAMAMOTO Takashi) wrote:
> > On Thu, Jan 28, 2010 at 06:42:16AM +0000, YAMAMOTO Takashi wrote:
> >  > > ISTM that section 9 is an appropriate place for both interface and
> >  > > implementation docs. In the (few) cases where we actually have an
> >  > > interface, as opposed to "some exposed pieces of the implementation",
> >  > > the documentation should be clear on which is which and which
> >  > > properties of the implementation are actually guaranteed by the
> >  > > interface and which aren't.
> >  > 
> >  > let's stop being too generic and go back to the change in question.
> >  > do you think this man page is an appropriate place for these functions?
> > 
> > Given that they exist in several MD implementations and (I think) are
> > more or less the same in at least some of those, yes, provided they're
> > documented as a piece of internals.
> 
> "some MD implementations might have this for their internal use"?
> it sounds useless and confusing to me.
> 
> comments along the code itself is far more appropriate for this kind
> of descriptions because they have more chance to be up-to-date and
> someone who cares MD implementation details likely will look at the code
> anyway.

Fully agree.

While it would be great to have implementation documents, I do not think
it is realistic due to a simple lack of man power (see NetBSD Internals
project).  There are still many undocumented and/or outdated interfaces
in section 9, which is a much higher priority.  For implementation docs,
leaving good comments in the source code is perfectly enough.

-- 
Mindaugas