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

From: Junio C Hamano <[email-masked]>
Date: Tue, 29 Apr 2025 10:01:21 -0700

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

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