y...@mwd.biglobe.ne.jp (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
