Subject: Re: 1. uiopeek? 2. hashinit/hashdone?
To: None <firstname.lastname@example.org>
From: Thor Lancelot Simon <email@example.com>
Date: 06/04/2006 19:24:04
On Sun, Jun 04, 2006 at 07:13:04PM -0400, firstname.lastname@example.org wrote:
> 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.
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.
I've met too many programmers who only care if the code compiles. I am
sure that for them, a simple format specification of the API is sufficient.