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,
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html