[m-rev.] Re: missing library documentation

[Fergus Henderson]

On 19-Aug-2002, Zoltan Somogyi <zs at cs.mu.OZ.AU> wrote:
> On 19-Aug-2002, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > I noticed that there is no documentation for the library routines
> > *_upper_bound_search and *_lower_bound_search.  Could you please
> > add some?
> 
> Done. Will you volunteer to document the rest of these modules :-)
> 
> library/bintree.m:
> library/map.m:
> library/tree234.m:
> 	Copy the documentation of the lower and upper search and lookup
> 	predicates from rbtree.m to these modules as well.

For map.m, I think all the routines other than *_bound_search
are already documented.

For tree234.m, there is a comment at the top saying "see map.m for
documentation".  I think that is sufficient.

For bintree.m, the module is deprecated (and has been since 1995).
I'd rather remove it than document it.
Currently it's used only in library/bintree_set.m, and we could
change that module to use tree234.m.  Any objections?

> Index: tree234.m
...
> +	% Search for a key-value pair using the key.  If there is no entry
> +	% for the given key, returns the pair for the next lower key instead.
> +	% Fails if there is no key with the given or lower value.
>  :- pred tree234__lower_bound_search(tree234(K, V), K, K, V).
>  :- mode tree234__lower_bound_search(in, in, out, out) is semidet.
...

I think it would be better *not* to add this documentation here,
instead relying on the comment at the top of the module.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------