Bill Squier wrote:

> Knowing briefly what the sysctl knob will change right there in the 
> output of
> sysctl -a seems like a win to me-- and a much bigger one that knowing
> that my PIII supports the ABCDEFG-HOOKED-ON-PHONICS-WORKED-FOR-ME flag.

This feature does not need to be in the kernel: it can be in sysctl(8). 
I guess the semantics for a given sysctl variable never or rarely 
changes, so that if a description exists, it will likely be correct.

And if the feature is so much used as you say (which I am inclined to 
believe), the documentation slots will get filled in pretty quickly.

I repeat what others have said too: the kernel is not the right place 
for documentation.

However, maybe the problem has its roots deeper: IIUC all the changes 
made recently to the sysctl functionality were to avoid 
desynchronization between kernel and userland; while we can pay some 
little tradeoff for this because it really helps updating the kernel 
and not the tools, pushing this to having the documentation in sync is 
conceptually clean, but not appropriate for a kernel.

  Aymeric