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

Or to come at the same point a slightly different way:

The audience I had in mind was a programmer who has a firm abstract
understanding of a hash table, and wants to know how to use this
particular interface to make one. S/he already has a mental picture
of an abstract data type defined by

 - some number of slots, to be derived from
   an expected capacity
   / a design load factor
 - some function mapping from keys to hashes (Xr hash 9)
 - some function to reduce hashes to slot indices (%prime?  &mask?)
 - some mechanism for resolving collisions (chaining? open addressing?)

and is reading the man page to find out "how do I map this picture onto
this API?" If the page doesn't answer /those/ questions, it has failed:
those are not under-the-hood magic, they are the driving controls, and
the reader should not have to detour through the source to find them.
Likewise, questions like "when could this return NULL?" "what happens if
I hashdone a nonempty table?" "how does my choice of LIST/TAILQ affect
allocation size?" strike me as well within the reader's right to ask,
and to expect to see answered.

Now, the objection about internals I can see more plausibly applying
to some other spots in the page, such as "The mtype and mflags arguments
are passed to malloc." A purist could reasonably insist that I mean the
flags are those defined in malloc.h and mean the same thing, but should
avoid making the commitment that the work will actually be done by calling
malloc with them. I would grant that point; I just gave up on finding a
purist way to say it that didn't sound awkward even to me. :)

Thor, how the devil DO you use this beast for non-power-of-two hash
sizes?  That eluded even me.  FreeBSD's added a separate phashinit
for that....

-Chap