Re: [PATCH v5 14/18] tree-walk.h API doc: improve documentation of get_tree_entry()

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 1, 2021, 20:30 UTC
Message-ID: <xmqq4kgp3fyh.fsf@gitster.g>
In-Reply-To: <patch-14.19-44f16d74426-20210331T190531Z-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

Show 27 quoted lines

> Change a mention of sha1 to OID and change the comment to a listing of
> functions discussed below, right now there's only one function, but
> subsequent commits will add more.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  tree-walk.h | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/tree-walk.h b/tree-walk.h
> index 09e40d9221d..cd8da84f56c 100644
> --- a/tree-walk.h
> +++ b/tree-walk.h
> @@ -166,11 +166,13 @@ 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 OID 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.
> + * You always need a pointer to an appropriate variable to fill in
> + * (NULL won't do!). That variable is:
> + *
> + * get_tree_entry(): unsigned short mode

The last part after "That variable is:" makes no sense. Sent before completing?

The function takes a repository, tree object name, a path in that tree as input, and find the entry in the tree at the given path. Its finding is returned in the fourth and fifth parameters as

    struct object_id *oid
    unsigned short *mode

By the way, I think somebody forgot to update the description while inserting the "struct repository *" as the first parameter and that is where the "third and fourth" in the original comes from.