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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 29, 2025, 17:01 UTC
Message-ID: <xmqqr01a6gwu.fsf@gitster.g>
In-Reply-To: <pull.1912.git.1745941503913.gitgitgadget@gmail.com>

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

Show 9 quoted lines

> 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.

Show 15 quoted lines

>  /**
>   * 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.