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:36:34
On Sun, 4 Jun 2006, Thor Lancelot Simon wrote:
> Unfortunately, often the only easy way to give an adequate explanation of
> "what does this API" do -- when "how long does it take/how much memory
> does it use" are considered part of what it "does", which for code like
> sorting or hashing code it's simply insane not to -- is to answer the
> question of "how it works". This, in fact, is exactly such a case.
The source already answers that question, though. Do you really think it's
a good idea to document things in multiple places? A good interface should
not leak many of the details of the implementation, because it makes it
harder to change the underlying implementation.
That aside though, even if your interface does imply a specific
implementation (that is, you cant make use of it without knowing the
underlying implementation), you STILL don't need to document it in a man
page, that's what the source code is for. If the implementation is
particularly complex, that source code should be commented, so atleast if
someone wants to change the implementation, they only have to modify a
The documentation can then give interface details, and the location of the
implementation. I'm not sure what the downside to this would be. My real
fear here is that man pages will get written once and a few years from
now, will document an implementation that is no longer accurate. That
said, flawed possibly inaccurate documentation trumps no documentation.