[v3,1/2] worktree: update documentation for lock_reason and lock_reason_valid
diff mbox series

Message ID 20181030062409.42169-1-nbelakovski@gmail.com
State New
Headers show
Series
  • [v3,1/2] worktree: update documentation for lock_reason and lock_reason_valid
Related show

Commit Message

Nickolai Belakovski Oct. 30, 2018, 6:24 a.m. UTC
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(-)

Comments

Junio C Hamano Oct. 31, 2018, 2:28 a.m. UTC | #1
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.

Patch
diff mbox series

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 */
 	struct object_id head_oid;
 	int is_detached;
 	int is_bare;
 	int is_current;
-	int lock_reason_valid;
+	int lock_reason_valid; /* private */
 };
 
 /* Functions for acting on the information about worktrees. */