Re: [bug-patch] [PATCH] plug a leak

[Jim Meyering]

Andreas Gruenbacher wrote:
> On Wednesday 25 May 2011 15:12:35 Jim Meyering wrote:
>> I can see the advantage of using the goto (single point of return and *PY is
>> always set).  However, using the goto suggests you'd have to update the
>> description to say what *PY = -1 means, but will any caller even care?
>> Probably not, but I haven't checked that.
>
> If a value > max is returned, *py is ignored.  Not sure there is much value in
> explicitly documenting this ...

I now realize why I chose not to modify *PY:
Returning MAX+1 is all that is necessary.  Doing any more (like
setting *PY) is best avoided in general (keep API's minimalist),
because some caller might be tempted to test *PY rather than the
return value.

I propose to document that:

diff --git a/src/bestmatch.h b/src/bestmatch.h
index a162bb5..02f961c 100644
--- a/src/bestmatch.h
+++ b/src/bestmatch.h
@@ -36,7 +36,7 @@
  *
  * Returns the number of changes (insertions and deletions) required to get
  * from a[] to b[].  Returns MAX + 1 if a[] cannot be turned into b[] with
- * MAX or fewer changes.
+ * MAX or fewer changes, in which case *PY is not modified.
  *
  * MIN specifies the minimum number of elements in which a[] and b[] must
  * match. This allows to prevent trivial matches in which a sequence is