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 -- 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
