Re: CVS commit: src

[Jukka Ruohonen <jruohonen%iki.fi@localhost>]

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.