Re: CVS commit: src

[David Holland <dholland-sourcechanges%netbsd.org@localhost>]

On Tue, Jan 26, 2010 at 12:25:00PM +0000, David Brownlee wrote:
 > > ... 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.

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.

After all, sometimes people are working on the internals, at which
point documentation that says no more than "this is internal, go away"
is useless -- rather like when a system administrator finds docs
saying "consult your system administrator for more information".

 > 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

What constitutes "implementation" is context-dependent. For example,
VOP_LOOKUP is private implementation material if you're working in the
syscall layer, but an important interface if you're hacking namei or
writing a FS.

If for no other reason than this, I don't think making another section
is a good idea.

 > b) Must all carry the line "implementation specific and subject to
 > change", and "as of NetBSD x", eg: 5.99.23

that's true of everything in section 9.

-- 
David A. Holland
dholland%netbsd.org@localhost