Ben Collins-Sussman <sussman@collab.net> writes:
> > + * If @a locks is not @c NULL, maps hash entry names (<tt>const
> > char *</tt>)
> > + * to @c svn_lock_t *'s doing all allocation in @a pool.
>
> This language is ambiguous. Why would locks be NULL? Is it because
> the caller is passing in a NULL pointer, or might the function return
> NULL?
>
> The wording needs to be changed in this docstring; we need make it
> clear that *if* the caller passes in a non-NULL **locks argument,
> then the function will set it to a hash which maps [blah] to [blah].
One important convention: you could mean "if @a locks is not @c NULL",
or you could mean "if @a *locks is not @c NULL" (note the asterisk).
In this case, I think you did write what you meant, but make it
clearer by saying precisely what the function will do:
If @a locks is not @c NULL, set @a *locks to a hash table mapping
entry names (<tt>const char *</tt>) to @c svn_lock_t *'s,
allocating both @a *locks and everything inside it in @a pool.
(Of course, if that's not the exact behavior, then change the wording
accordingly, I'm just trying to give you an idea of how to phrase it.)
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Aug 9 19:39:57 2005