On Sun, Jun 04, 2006 at 07:13:04PM -0400, brian@surge.insomnia.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.

Thor