Re: [PATCH v5 09/35] lockfile.c: document the various states of lock_file objects

2014-09-22 Thread Michael Haggerty
On 09/16/2014 11:03 PM, Jonathan Nieder wrote: 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:

Re: [PATCH v5 09/35] lockfile.c: document the various states of lock_file objects

2014-09-22 Thread Jonathan Nieder
Michael Haggerty wrote: I agree with your point about overlap. I will split the documentation into two parts with less redundancy: * Documentation/technical/api-lockfile.txt: How to use the API. * lockfile.{c,h}: Internal implementation details. I think the implementation details would

[PATCH v5 09/35] lockfile.c: document the various states of lock_file objects

2014-09-16 Thread Michael Haggerty
Document the valid states of lock_file objects, how they get into each state, and how the state is encoded in the object's fields. Signed-off-by: Michael Haggerty mhag...@alum.mit.edu Reviewed-by: Ronnie Sahlberg sahlb...@google.com --- lockfile.c | 57

Re: [PATCH v5 09/35] lockfile.c: document the various states of lock_file objects

2014-09-16 Thread Jonathan Nieder
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