[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
Re: CVS commit: src
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
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.
Main Index |
Thread Index |