Subject: Re: 1. uiopeek? 2. hashinit/hashdone?
To: Thor Lancelot Simon <email@example.com>
From: None <firstname.lastname@example.org>
Date: 06/04/2006 19:13:04
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
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