From: Junio C Hamano Date: Wed, 31 Oct 2018 02:28:35 GMT Subject: Re: [PATCH v3 1/2] worktree: update documentation for lock_reason and lock_reason_valid Message-ID: In-Reply-To: <20181030062409.42169-1-nbelakovski@gmail.com> nbelakovski@gmail.com writes: > From: Nickolai Belakovski > > 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 > --- > 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.