On Thu, Mar 25, 2010 at 04:50:03PM +0000, David Holland wrote: > We just went around on this like two or three weeks ago on spl > internals. On the one hand, the man page should document the > interface, not the implementation; on the other hand, anything global > someone might run across while debugging or rototilling should be > documented. The resolution the last time was to document the internals > in a different man page. (And if we weren't out of man sections, it > would seem like a good section distinction: kernel interfaces > vs. kernel internals...)
I am with the David here. Rather than trying to draw a line on the water about what is allowed to be documented and what does not deserve to be documented, the rule should be: if it is global, does not impose considerable maintenance costs, and *may help someone to understand something*, it is worth documenting. Besides, it is not like what I wrote in there would go into deep implementation details; rather it just uses some technical jargon to describe what the variables are. We also have these implementation details exposed: $ sysctl kern.clockrate kern.clockrate: tick = 10000, tickadj = 40, hz = 100, profhz = 100, stathz = 100 But if someone comes up with a big hardcover monograph about NetBSD kernel internals, I am happy to start deleting documentation instead of writing it. -Jukka.
