Re: [RFC/PATCH] technical-docs: document tree-walking API

[Junio C Hamano <gitster@pobox.com>]

Stephen Boyd <bebarino@gmail.com> writes:

> Some things to get you started:
>
>       - the traversal callback mask parameter
> 	- a better general usage description at the top
> 	- add an authors section?

Thanks.

> diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt
> index e3ddf91..baa382d 100644

> +* `mask` has its nth bit set if the nth tree's entry is valid. (or different?)

nth bit is set when something exists in that tree at the path (entry[nth]
could be either a file (regular or symlink) or a directory).

> +* `dirmask` has its nth bit set if the nth tree's entry is a directory.

Correct.

> +* `entry` is an array of size `n` where the nth entry is from the nth tree.
> +
> +* `info` maintains the state of the traversal.
> +
> ++
> +Returning a negative value will terminate the traversal. Otherwise the
> +return value is treated as an update mask. If the nth bit is set the nth tree
> +will be updated and if the bit is not set the nth tree entry will be the
> +same in the next callback invocation.

Correct.