Re: [PATCH] path: document path functions

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

Brandon Williams <bmwill@google.com> writes:

> Signed-off-by: Brandon Williams <bmwill@google.com>
> ---
>
> As promised here is an update to the documentation for the path generating
> functions.
>
>  path.h | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------
>  1 file changed, 112 insertions(+), 21 deletions(-)
>
> diff --git a/path.h b/path.h
> index 9541620c7..1ccd0373c 100644
> --- a/path.h
> +++ b/path.h
> @@ -4,53 +4,144 @@
>  struct repository;
>  
>  /*
> - * Return a statically allocated filename, either generically (mkpath), in
> - * the repository directory (git_path), or in a submodule's repository
> - * directory (git_path_submodule). In all cases, note that the result
> - * may be overwritten by another call to _any_ of the functions. Consider
> - * using the safer "dup" or "strbuf" formats below (in some cases, the
> - * unsafe versions have already been removed).
> + * The result to all functions which return statically allocated memory may be
> + * overwritten by another call to _any_ one of these functions. Consider using
> + * the safer variants which operate on strbufs or return allocated memory.
>   */

The result of the update definitely is better, but stepping back a
bit, it still does not answer some questions the original did not:

 - is the resulting path absolute?  if relative, relative to what (cwd)?

 - what should a caller write in fmt?  can we have a couple of
   typical calling example?

 - does a caller need to know which hierarchies under $GIT_DIR are
   common and call git_common_path() for them, or does git_path()
   do the 'right' thing for the caller?  If latter, what's the use
   of git_common_path() for callers (outside the implementation of
   path.c API)?

Will queue.  Thanks.