1: ".Fn hashinit
function allocates and initializes space for a simple chaining hash table.
The number of slots will be the least power of two not smaller than
.Fa chains ,"

This seems to me to be a commitment to allocate based on power of two. 
Sure, the current implementation does this (going so far as getting into 
an infinite loop if elements is ~0 on most architectures), but is this a 
contract you want to provide?

My peferred language would be something like:
".Fn hashinit
function allocates and initializes space for a single chaining hash table.
The number of slots will be atleast chains in length

2: While on one hand, I don't like the mention of LIST and TAILQ, they 
have to be mentioned. It would be nice to mention that there may be more 
htypes added in the future, so one should not assume those are the only 
legal htypes (although they are in the current implementation, of course).

3: The documentation does not mention any limits on sizes of the chains. 
This should be added, since it would be nice if the contract explicitly 
forbidded hashsize * esize being > the value a u_long can store. I 
personally would have some macro defining the maximum, and document its 
existance (so it can vary among architectures).


On Sun, 4 Jun 2006, Chapman Flack wrote:

> Date: Sun, 04 Jun 2006 21:28:03 -0400
> From: Chapman Flack <nblists@anastigmatix.net>
> To: tech-kern@NetBSD.org
> Subject: Re: 1. uiopeek?  2. hashinit/hashdone?
> 
> brian@surge.insomnia.org wrote:
>> 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.
>
> I think it would help me to see examples of the points in which you
> think I have extended the contract.  I've already mentioned the things
> I think are inherent to any hashtable contract, that if they are
> unanswered force anyone to read the code just to decide whether to use
> it at all.  But I see a couple of places where I exposed unnecessarily.
> One I already mentioned, in saying that malloc is actually used rather
> than saying only the two arguments are as used by malloc.  Der Mouse
> just pointed out a less niggling one, that perhaps I should say the
> hashdone-non-empty behavior is undefined (with the usual menacing
> undertone on undefined) rather than actually saying it's unchecked.
> That strikes me as a worthwhile improvement.  Have you spotted more?
>
> -Chap
>
>