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
