[PATCH] tree-walk.h: fix incorrect API comment

[PATCH] tree-walk.h: fix incorrect API comment

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

When commit 50ddb089ff68 (tree-walk.c: remove the_repo from
get_tree_entry(), 2019-06-27) added an extra parameter to
get_tree_entry(), it did not fix the ordering comment about the meaning
of the parameters.  Rather than just changing "third"->"fourth" and
"fourth"->"fifth", give the paramemters meaningful names (or actually,
just take the existing names from the get_tree_entry() definition in the
tree-walk.c file) and strike the comment.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
    tree-walk.h: fix incorrect API comment

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1912%2Fnewren%2Ffix-tree-walk-api-comment-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1912/newren/fix-tree-walk-api-comment-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1912

 tree-walk.h | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/tree-walk.h b/tree-walk.h
index aaea689f9ae..226b535f085 100644
--- a/tree-walk.h
+++ b/tree-walk.h
@@ -177,10 +177,11 @@ struct traverse_info {
 
 /**
  * Find an entry in a tree given a pathname and the sha1 of a tree to
- * search. Returns 0 if the entry is found and -1 otherwise. The third
- * and fourth parameters are set to the entry's sha1 and mode respectively.
+ * search. Returns 0 if the entry is found and -1 otherwise.
  */
-int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);
+int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,
+		   const char *name, struct object_id *oid,
+		   unsigned short *mode);
 
 /**
  * Generate the full pathname of a tree entry based from the root of the

base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3
-- 
gitgitgadget

Re: [PATCH] tree-walk.h: fix incorrect API comment

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Elijah Newren <newren@gmail.com>
>
> When commit 50ddb089ff68 (tree-walk.c: remove the_repo from
> get_tree_entry(), 2019-06-27) added an extra parameter to
> get_tree_entry(), it did not fix the ordering comment about the meaning
> of the parameters.  Rather than just changing "third"->"fourth" and
> "fourth"->"fifth", give the paramemters meaningful names (or actually,
> just take the existing names from the get_tree_entry() definition in the
> tree-walk.c file) and strike the comment.

Please drop "and strike the comment" part.  The "oid" and "mode"
being out-parameters is significant for callers.

>  /**
>   * Find an entry in a tree given a pathname and the sha1 of a tree to
> - * search. Returns 0 if the entry is found and -1 otherwise. The third
> - * and fourth parameters are set to the entry's sha1 and mode respectively.
> + * search. Returns 0 if the entry is found and -1 otherwise.
>   */
> -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);
> +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,
> +		   const char *name, struct object_id *oid,
> +		   unsigned short *mode);
>  
>  /**
>   * Generate the full pathname of a tree entry based from the root of the
>
> base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3

	Find an entry with the "name" in a tree object "tree_oid",
	and return the the object name and the mode of the found
	entry via the "oid" and the "mode" parameters.  Return 0 if
	the entry is found, and -1 otherwise.

or something, perhaps.

Thanks.

[PATCH v2] tree-walk.h: fix incorrect API comment

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

When commit 50ddb089ff68 (tree-walk.c: remove the_repo from
get_tree_entry(), 2019-06-27) added an extra parameter to
get_tree_entry(), it did not fix the ordering comment about the meaning
of the parameters.  Rather than just changing "third"->"fourth" and
"fourth"->"fifth", give the paramemters meaningful names (or actually,
just take the existing names from the get_tree_entry() definition in the
tree-walk.c file) and while at it, tweak the rest of the description to
incorporate the other parameter names as well.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
    tree-walk.h: fix incorrect API comment
    
    Changes since v1:
    
     * Updated the documentation to explain that oid and mode are output
       parameters, and slightly tweaked the description further.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1912%2Fnewren%2Ffix-tree-walk-api-comment-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1912/newren/fix-tree-walk-api-comment-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1912

Range-diff vs v1:

 1:  6375bc7d351 ! 1:  a47aceb6394 tree-walk.h: fix incorrect API comment
     @@ Commit message
          of the parameters.  Rather than just changing "third"->"fourth" and
          "fourth"->"fifth", give the paramemters meaningful names (or actually,
          just take the existing names from the get_tree_entry() definition in the
     -    tree-walk.c file) and strike the comment.
     +    tree-walk.c file) and while at it, tweak the rest of the description to
     +    incorporate the other parameter names as well.
      
          Signed-off-by: Elijah Newren <newren@gmail.com>
      
       ## tree-walk.h ##
      @@ tree-walk.h: struct traverse_info {
     + };
       
       /**
     -  * Find an entry in a tree given a pathname and the sha1 of a tree to
     +- * Find an entry in a tree given a pathname and the sha1 of a tree to
      - * search. Returns 0 if the entry is found and -1 otherwise. The third
      - * and fourth parameters are set to the entry's sha1 and mode respectively.
     -+ * search. Returns 0 if the entry is found and -1 otherwise.
     -  */
     +- */
      -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);
     ++ * Walk trees starting with "tree_oid" to find the entry for "name", and
     ++ * return the the object name and the mode of the found entry via the
     ++ * "oid" and "mode" parameters.  Return 0 if the entry is found, and -1
     ++ * otherwise.
     ++ */
      +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,
      +		   const char *name, struct object_id *oid,
      +		   unsigned short *mode);


 tree-walk.h | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/tree-walk.h b/tree-walk.h
index aaea689f9ae..29a55328bd9 100644
--- a/tree-walk.h
+++ b/tree-walk.h
@@ -176,11 +176,14 @@ struct traverse_info {
 };
 
 /**
- * Find an entry in a tree given a pathname and the sha1 of a tree to
- * search. Returns 0 if the entry is found and -1 otherwise. The third
- * and fourth parameters are set to the entry's sha1 and mode respectively.
- */
-int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);
+ * Walk trees starting with "tree_oid" to find the entry for "name", and
+ * return the the object name and the mode of the found entry via the
+ * "oid" and "mode" parameters.  Return 0 if the entry is found, and -1
+ * otherwise.
+ */
+int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,
+		   const char *name, struct object_id *oid,
+		   unsigned short *mode);
 
 /**
  * Generate the full pathname of a tree entry based from the root of the

base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3
-- 
gitgitgadget