Re: CVS commit: src

[David Brownlee <abs%netbsd.org@localhost>]

2010/1/26 Andrew Doran <ad%netbsd.org@localhost>
>
> On Wed, Nov 18, 2009 at 11:35:15PM +0000, YAMAMOTO Takashi wrote:
> >
> > > On Wed, Nov 18, 2009 at 01:29:05AM +0000, YAMAMOTO Takashi wrote:
> > >>
> > >> > 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.

I think its safe to say that the best place to keep implementation
documentation is with the code (at least in the same tree) so it can
track changes, and from there its a small step to shipping the
documentation with the system.

Whether that is in manpages which are specifically tagged as
'implementation specific and subject to change', in a different man
section (9i?), or somewhere else in /usr/share which can be referenced
by manpages is open to debate, though I think it would help if we had
a policy so everyone knew what to expect.

Ideally those contributing and using the documentation most should
have the biggest say, but just to throw up a strawman how about:

Implementation manpages:
a) Go in section 9i
b) Must all carry the line "implementation specific and subject to
change", and "as of NetBSD x", eg: 5.99.23
c) Should reference source files which include relevant definitions
d) Source files that include relevant definitions should include a
well defined reference to the manpage with a note to keep updated
e) Its fine for a manpage (9 or 9i) to include "this is documented
futher/fully in source file ${foo}"