Re: [PATCH v2 01/16] Move lockfile documentation to lockfile.h and lockfile.c

[Junio C Hamano <gitster@pobox.com>]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> Rearrange/rewrite it somewhat to fit its new environment.
> ...
> diff --git a/lockfile.h b/lockfile.h
> index b4abc61..a483cc9 100644
> --- a/lockfile.h
> +++ b/lockfile.h
> @@ -4,54 +4,103 @@
> ...
> @@ -68,16 +117,51 @@ struct lock_file {
>  #define LOCK_SUFFIX ".lock"
>  #define LOCK_SUFFIX_LEN 5
>  
> +
> +/*
> + * Flags
> + * -----
> + *
> + * The following flags can be passed to `hold_lock_file_for_update()`
> + * or `hold_lock_file_for_append()`.
> + */
> +
> +/*
> + * If a lock is already taken for the file, `die()` with an error
> + * message. If this flag is not specified, trying to lock a file that
> + * is already locked returns -1 to the caller.
> + */
>  #define LOCK_DIE_ON_ERROR 1
> +
> +/*
> + * Usually symbolic links in the destination path are resolved. This
> + * means that (1) the lockfile is created by adding ".lock" to the
> + * resolved path, and (2) upon commit, the resolved path is
> + * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile
> + * is created by adding ".lock" to the path argument itself. This
> + * option is used, for example, when detaching a symbolic reference,
> + * which for backwards-compatibility reasons, can be a symbolic link
> + * containing the name of the referred-to-reference.
> + */
> ...

Thanks.  I really like the way these per-item descriptions explain
each item much better.  The old documentation may have contained all
the same info, but a better organization makes a big difference.