Re: [PATCH v3 1/2] worktree: update documentation for lock_reason and lock_reason_valid
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 31, 2018, 02:28 UTC
- Message-ID
- <xmqqlg6ezw6k.fsf@gitster-ct.c.googlers.com>
- In-Reply-To
- <20181030062409.42169-1-nbelakovski@gmail.com>
nbelakovski@gmail.com writes:
Show 21 quoted lines
> 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.
Show 7 quoted lines
> 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.