Re: [PATCH v3 1/2] worktree: update documentation for lock_reason and lock_reason_valid

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

nbelakovski@gmail.com writes:

> From: Nickolai Belakovski <nbelakovski@gmail.com>
>
> Clarify that these fields are to be considered implementation details
> and direct the reader to use the is_worktree_locked function to retrieve
> said information.
>
> Signed-off-by: Nickolai Belakovski <nbelakovski@gmail.com>
> ---
>  worktree.h | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/worktree.h b/worktree.h
> index df3fc30f7..6b12a3cf6 100644
> --- a/worktree.h
> +++ b/worktree.h
> @@ -10,12 +10,12 @@ struct worktree {
>  	char *path;
>  	char *id;
>  	char *head_ref;		/* NULL if HEAD is broken or detached */
> -	char *lock_reason;	/* internal use */
> +	char *lock_reason;	/* private - use is_worktree_locked */

s/use /used by/, probably.

>  	struct object_id head_oid;
>  	int is_detached;
>  	int is_bare;
>  	int is_current;
> -	int lock_reason_valid;
> +	int lock_reason_valid; /* private */
>  };

These annotations to the two fields are not wrong per-se, but I have
a feeling that it would equally be important to document what the
other "non-private" fields mean, if peeking them *is* the API this
subsystem offers.

Thanks.