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 dholl...@netbsd.org
