Re: [PATCH] add technical documentation about ref iteration

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 3, 2011, 19:10 UTC
Message-ID: <7vei12b9aq.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110803180319.GA13057@sandbox-rc>

Heiko Voigt <hvoigt@hvoigt.net> writes:

Show 5 quoted lines

> 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

Show 8 quoted lines

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