Re: [PATCH 5/6] Document a bunch of functions defined in sha1_file.c

Hi,

Michael Haggerty wrote:

No, this hasn't changed.  I've been documenting public functions in the
header files above the declaration, and private ones where they are
defined.  So I moved the documentation for this function to cache.h:

+/*
+ * Return the name of the file in the local object database that would
+ * be used to store a loose object with the specified sha1.  The
+ * return value is a pointer to a statically allocated buffer that is
+ * overwritten each time the function is called.
+ */
 extern const char *sha1_file_name(const unsigned char *sha1);

I also rewrite the comment, as you can see.  The "NOTE!" seemed a bit
overboard to me, given that there are a lot of functions in our codebase
that behave similarly.  So I toned the warning down, and tightened up
the comment overall.

Let me know if you think I've made it less helpful.

In the present state of the codebase, where many important functions
have no documentation or out-of-date documentation, the first place I
look to understand a function is its point of definition.  So I do
think that moving docs to the header file makes it less helpful.  I'd
prefer a mass move in the opposite direction (from header files to the
point of definition).

On the other hand I don't feel strongly about it.

Hope that helps,
Jonathan