From: Jonathan Nieder <jrnieder@gmail.com>
Date: Tue, 16 Sep 2014 21:03:17 GMT
Subject: Re: [PATCH v5 09/35] lockfile.c: document the various states of lock_file objects
Message-ID: <20140916210317.GJ29050@google.com>
In-Reply-To: <1410896036-12750-10-git-send-email-mhagger@alum.mit.edu>

Michael Haggerty wrote:

> --- a/lockfile.c
> +++ b/lockfile.c
> @@ -4,6 +4,63 @@
>  #include "cache.h"
>  #include "sigchain.h"
>
> +/*
> + * File write-locks as used by Git.
> + *
> + * When a file at $FILENAME needs to be written, it is done as
> + * follows:

This overlaps a lot with the API doc, which makes me worry a little
about it going out of date.  Would improving the API doc help, or if
aspects are especially relevant here, is there a way to summarize them
more quickly to avoid some of the redundancy?

[...]
> + * A lock_file object can be in several states:

Would it make sense for this information to go near the definition of
'struct lock_file'?  That's where I'd start if I were looking for
information on what states a lock_file can be in.

My two cents,
Jonathan