Re: [PATCH v3 18/19] setup.c: document get_pathspec()

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

Adam Spiers <git@adamspiers.org> writes:

> Since we have just created a new pathspec-handling library, now is a
> good time to add some comments explaining get_pathspec().
>
> Signed-off-by: Adam Spiers <git@adamspiers.org>
> ---

Yes, but we would rather not to see new users of this function added
to our codebase in its current form, as explained in the nearby
comment.  We would want to migrate everybody to "struct pathspec"
based interface to support magic pathspecs in the longer term.

>  setup.c | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
>
> diff --git a/setup.c b/setup.c
> index 7663a4c..03d6d5c 100644
> --- a/setup.c
> +++ b/setup.c
> @@ -249,6 +249,21 @@ static const char *prefix_pathspec(const char *prefix, int prefixlen, const char
>  		return prefix_path(prefix, prefixlen, copyfrom);
>  }
>  
> +/*
> + * prefix - a path relative to the root of the working tree
> + * pathspec - a list of paths underneath the prefix path
> + *
> + * Iterates over pathspec, prepending each path with prefix,
> + * and return the resulting list.
> + *
> + * If pathspec is empty, return a singleton list containing prefix.
> + *
> + * If pathspec and prefix are both empty, return an empty list.
> + *
> + * This is typically used by built-in commands such as add.c, in order
> + * to normalize argv arguments provided to the built-in into a list of
> + * paths to process, all relative to the root of the working tree.
> + */
>  const char **get_pathspec(const char *prefix, const char **pathspec)
>  {
>  	const char *entry = *pathspec;