Re: CVS commit: src

[Andrew Doran <ad%NetBSD.org@localhost>]

On Wed, Nov 18, 2009 at 11:35:15PM +0000, YAMAMOTO Takashi wrote:
> hi,
> 
> > On Wed, Nov 18, 2009 at 01:29:05AM +0000, YAMAMOTO Takashi wrote:
> >> hi,
> >> 
> >> > Module Name:     src
> >> > Committed By:    dyoung
> >> > Date:            Tue Nov 17 18:36:07 UTC 2009
> >> > 
> >> > Modified Files:
> >> >  src/distrib/sets/lists/comp: mi
> >> >  src/share/man/man9: Makefile spl.9
> >> > 
> >> > Log Message:
> >> > Describe spllower(9) and splraise(9).
> >> 
> >> these are MD implementation details which are not appropriate to be
> >> described in this page.  please revert.
> >> adding xrefs to splraiseipl and makeiplcookie instead is probably
> >> a good idea.
> > 
> > I see.  I will describe spllower(9) and splraise(9) in an i386 page,
> > instead.
> 
> imo, for internal functions like them, it's more appropriate to put
> comments in the source code than man pages.

... or in a book about the kernel.  Section 9 describes how to use kernel
facilities, not how they work internally.  By documenting this item you
give the impression of availability and stability, neither of which is
provided.