[PATCH 02 of 10] graphmod/graphlog: move log walks to graphmod

[Sune Foldager]

timeless wrote:
> On Fri, May 15, 2009 at 10:16 PM, Peter Arrenbrecht
> <peter.arrenbrecht at gmail.com> wrote:
>   
>> +    This generator function walks through the revision history from revision
>> +    start to revision stop (which must be less than or equal to start).
>>     
>
> I know you're just moving this comment and that the variables are
> named to match, but i find "start" and "stop" don't seem to fit well.
> [...]
> start [1] is only available as a verb and a noun,
> stop [2] is available as a verb, noun, and adjective.
> revision [3] is always a noun
> [...]
> Typically in English, you can have <noun phrase> = <adj> <noun>, and
> that's a likely thing to appear where the text uses "revision start"
> and "revision stop".
>   
I think we should ackknowledge that this is in-program documentation for 
other programmers, and not high poetry. After all, the average novel 
writer doesn't have to deal with refering to variables and other 
technical devices in her text. We do, so sometimes sentences might be a 
bit excentric, but I don't believe anyone who can read python would 
misunderstand this particular docstring :-). We also want to keep it 
short, after all.

-- 
Sune.