tree-walk.h: fix incorrect API comment

[newren]

Changes since v1:

• Updated the documentation to explain that oid and mode are output parameters, and slightly tweaked the description further.

[newren]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1912/newren/fix-tree-walk-api-comment-v1

To fetch this version to local tag pr-1912/newren/fix-tree-walk-api-comment-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1912/newren/fix-tree-walk-api-comment-v1

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Elijah Newren via GitGitGadget" <[email protected]> writes:

> From: Elijah Newren <[email protected]>
>
> 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.

[newren]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1912/newren/fix-tree-walk-api-comment-v2

To fetch this version to local tag pr-1912/newren/fix-tree-walk-api-comment-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1912/newren/fix-tree-walk-api-comment-v2

[gitgitgadget]

This patch series was integrated into seen via git@a5925c3.