[PATCH] dirstate: add/improve method docstrings and some comments

[Greg Ward]

On Fri, Sep 25, 2009 at 7:09 PM, Adrian Buehlmann <adrian at cadifra.com> wrote:
> Ugh. Does that help?

Very much, thank you.  I'm inclined to agree with Martin, that this
particular bit of code is sufficiently tricky and subtle that it needs
further explanation.  If the code had been completely understandable
as it is, then I wouldn't have been asking questions about it.

(I should say that in general, reading the Mercurial source has taught
me two things: clear code doesn't need many comments, and never use
one-letter variable names.  So yeah, in general I agree with your
stance on comments, but this is an exceptional case.  Furthermore,
it's a case that spills out of dirstate and affects other areas:
anyone calling dirstate.status() has to be aware of this.   My
proposed docstring for dirstate.status() should help there, I think.)

I'll see if I can distill your lengthy explanation down to something
concise, correct, and still useful, and the resend my patch.  I like a
good challenge.  ;-)

Greg