Re: [PATCH] add technical documentation about ref iteration

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

Heiko Voigt <hvoigt@hvoigt.net> writes:

> Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
> ---
>  Documentation/technical/api-ref-iteration.txt |   73 +++++++++++++++++++++++++
>  1 files changed, 73 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/technical/api-ref-iteration.txt

> +Submodules
> +----------
> +
> +If you want to iterate the refs of a submodule you first need to call
> +
> +	add_submodule_odb(submodule)
> +
> +and test whether that succeeds.

Hmm, this should probably be explained a bit deeper or not at all. For
example, what is "submodule" here? A path to the submodule directory? The
name of submodule? What is the unwanted consequence of adding this extra
object database into your process (e.g. you can no longer tell if an
object exists in the superproject, as it may now come from the submodule's
object database)? Can you get rid of it? How does this function signal
failures? What is the symptom if you forget this call and used the
iteration in the submodule (e.g. "we do not see any ref"; "we see only
some ref but not all"; "the call crashes the process")?

> +
> +(Heiko Voigt)

Please drop this line for two reasons.

Initially I added these parenthesized names at the end for placeholder
pages to name people who are responsible for the _code_ the document
describes, so that the ones who help documentation would know who to nag
to get the necessary information. With your description, people who are
interested in documenting this API more would know that for_each_ref() and
friends are the topic and can find out whom to harrass.

Besides, with only two commits to refs.c, I doubt you would want to be the
primary source of information for other people to bug in order to enhance
the API description in this file.

Thanks.