Re: [PATCH 01/14] cache.h: add comments for git_path() and git_path_submodule()

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 13, 2011, 18:37 UTC
Message-ID: <7vvcrs4u2b.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1318492715-5931-2-git-send-email-mhagger@alum.mit.edu>

mhagger@alum.mit.edu writes:

Show 8 quoted lines

> +
> +/*
> + * Return the path of a file within get_git_dir().  The arguments
> + * should be printf-like arguments that produce the filename relative
> + * to get_git_dir().  Return the resulting path, or "/bad-path/" if
> + * there is an error.
> + */
>  extern char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)));

Ok.

> +/*
> + * Return the path of a file within the submodule located at path.

This is confusing. Does this "file within the submodule" refer to files like "Makefile" tracked in a submodule at "dir"? Your description for git_path() above makes it clear that the function is about files like "index" and "HEAD" that are part of the control information for the current project, but the above gives an impression that you are talking about files in the working tree of the submodule.

> + * The other arguments should be printf-like arguments that produce
> + * the filename relative to "<path>/.git".  If "<path>/.git" is a

And the reader is puzzled by the sudden mention of <path>/.git here.

Show 5 quoted lines

> + * gitlink file, follow it to find the actual submodule git path.
> + * Return the resulting path, or "/bad-path/" if there is an error.
> + */
>  extern char *git_path_submodule(const char *path, const char *fmt, ...)
>  	__attribute__((format (printf, 2, 3)));