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

On 02/24/2014 07:18 PM, Jakub Narębski wrote:

Michael Haggerty wrote:

quoted

-/*
- * NOTE! This returns a statically allocated buffer, so you have to be
- * careful about using it. Do an "xstrdup()" if you need to save the
- * filename.
- *
- * Also note that this returns the location for creating.  Reading
- * SHA1 file can happen from any alternate directory listed in the
- * DB_ENVIRONMENT environment variable if it is not found in
- * the primary object database.
- */
  const char *sha1_file_name(const unsigned char *sha1)

Has this changed?

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.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/