Brandon Williams <bmwill@xxxxxxxxxx> writes: > Signed-off-by: Brandon Williams <bmwill@xxxxxxxxxx> > --- > > 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.
