On Thu, 2009-10-15 at 00:43 +0100, Julian Foad wrote:
> Paul,
>
> Reviewing r39019 for back-port, I struggled to understand the doc string
> of combine_with_lastrange(). It seemed to say bits and pieces about what
> it did internally, without saying what its purpose or promises or
> requirements were. I read through its implementation and its uses and
> re-wrote the doc string as in the attached patch. I found that the
> "lastrange" parameter was functionally redundant so I removed it, as it
> just made the interface to the function more complex.
Having slept on it... ew, I sound really grumpy. No weasel words in
there :-) It's difficult to document something you're totally immersed
in, in a way that works for people who are not already there. It did say
most of the things it needed to, in one way or another, but my re-write
tries to say them in a "top-down" direction from overall purpose through
conditions that are true in all cases and then down to the details of
all variations.
- Julian
> Please review the patch if you would.
>
> Thanks.
> - Julian
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2407823
Received on 2009-10-15 11:30:41 CEST