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

[Greg Ward]

On Sun, Sep 27, 2009 at 5:53 AM, Adrian Buehlmann <adrian at cadifra.com> wrote:
> I have come to the conclusion that the granularity setting
> is pointless up to the level that it starts harming. It doesn't
> harm program execution but it does harm understanding of the code.

Oh good.  I realized the second part (harms understanding) several
days ago, and strongly suspected the first part.

> It should be removed. We simply don't need it, it complicates
> matters for no good reason.

+1

> I'm proposing the following change, which also introduces considerable
> amount of new comment:

Nearly perfect.  Finally I can contribute something other than
questions: my expertise as a native English speaker!

> +        # taking the modification time of the newly created temporary file as
> +        # the filesystem's notion of 'now'
> +        now = util.fstat(st).st_mtime

"Use the modification time of the newly created temporary file as
the filesystem's notion of 'now'."

> +            if e[0] == 'n' and e[3] == now:
> +                # The file was modified at "the same moment" (e.g. within the
> +                # same second for filesystems like ext3) as we write dirstate.

"The file was modified "simultaneously" (e.g. within the same second for
filesystems with 1 sec granularity) with the current write to dirstate."

> +                # This commonly happens for at least a couple of files on
> +                # update. The user could change the file without changing its
> +                # size immediately after the close of the transaction but still
> +                # within the same second.

"... immediately after closing the transaction ..."

> +                # Avoid to mistreat such files as clean in future status calls
> +                # by invalidating the file's stat data in dirstate, forcing a
> +                # file compare on future status calls.

"Invalidate the file's stat data in dirstate, forcing future 'status'
calls to compare file contents.  This prevents mistakenly treating
such files as clean."

This will greatly improve the understandability of dirstate.  Thank you!

Greg