Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes:
> Document and format the argument list of the tree_entry_extract()
> function in preparation for eventually adding a sister function.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx>
> ---
> tree-walk.h | 14 ++++++++++----
> 1 file changed, 10 insertions(+), 4 deletions(-)
>
> diff --git a/tree-walk.h b/tree-walk.h
> index c60667cba8f..52eb0d6b5b3 100644
> --- a/tree-walk.h
> +++ b/tree-walk.h
> @@ -38,11 +38,17 @@ struct tree_desc {
>
> /**
> * Decode the entry currently being visited (the one pointed to by
> - * `tree_desc's` `entry` member) and return the sha1 of the entry. The
> - * `pathp` and `modep` arguments are set to the entry's pathname and mode
> - * respectively.
> + * `tree_desc's` `entry` member) and return the OID of the entry.
> + *
> + * There are variants of this function depending on what fields in the
> + * "struct name_entry" you'd like. You always need a pointer to an
> + * appropriate variable to fill in (NULL won't do!):
There aren't. At least not yet. So if you want to build a series
like this that does many little things in each step, stop this step
at updating SHA-1 to OID and do nothing else, until you introduce
different variant.
What is missing in the current description that is more worth
describing for those who are new to the codebase is probably the
fact that this is meant to be used in pairs with update_tree_entry().
You call extract, which does not change the entry at all, and when
you are done, update knows (from the data kept in the entry) where
the next entry is in memory and the entry is updated to point there.
Thanks.
> + *
> + * tree_entry_extract(): const char *path, unsigned int mode
> */
> -static inline const struct object_id *tree_entry_extract(struct tree_desc *desc, const char **pathp, unsigned short *modep)
> +static inline const struct object_id *tree_entry_extract(struct tree_desc *desc,
> + const char **pathp,
> + unsigned short *modep)
> {
> *pathp = desc->entry.path;
> *modep = desc->entry.mode;
