On Sun, 4 Jun 2006, Chapman Flack wrote:

> 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.

It all comes down to what is in the interface contract. Anything you 
document becomes part of that contract to the outside world, and thus 
difficult to change. That's all I was saying.

However, I will say that I think a more useful form of documentation which 
does not exist would be a general roadmap to the kernel sources, and how 
the pieces are related in addition to places to go to find the actual 
implementation. Documentation sort of between D&I and the source code -- 
not to replicate the sources, but more of a table of contents of the 
sources, if that makes any sense.

> 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. :)

Any documentation is better than no documentation, as long as you are 
concious of the fact that by documenting internal parts of the interface, 
you are extending the contract.