On Sun, 4 Jun 2006, Thor Lancelot Simon wrote:

> The problem is that the bare description of the interface you
> propose is not sufficient in this case, because our implementation
> has slightly different performance characteristics than those the
> readers of the manual page may be familiar with from other 4.4
> variants -- so we really do need to say something about how it
> works inside.

I'm not a commiter, but I do occssionally produced localized changes on 
netbsd (and others). My opinion comes from that standpoint alone...

Man pages documenting what a given api does are great things, they let me 
quickly write code without having to trod through the source of a bunch of 
functions; the implementations of which, I just don't care about. These 
man pages should always answer the question of what does this api do. 
However, it would be an error to also answer the question of how does this 
api work.

The problem with answering the how question is it creates a dependency; 
your documentation is now tied to the source, and vice versa. There is a 
real risk that changes could be made to the implementation (but not the 
interface) that make the man page become decynced from reality, so 
suddenly you make a change to the implementations of a, b, and c and have 
to update their man pages too, because implementation details are recorded 
in two different places.

As a consumer of this information, I just want to know about the interface 
you are providing; if I need to know about how it is implemented, then I 
can either read the source, or read supplementary documentation on the 
feature (which should exist for major features, in the form of papers or 
something, if at all possible).

Just my $0.02