On 02/24/2014 09:08 PM, Jonathan Nieder wrote: > Michael Haggerty wrote: >> [...] I've been documenting public functions in the >> header files above the declaration, and private ones where they are >> defined. [...] >> >> 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.
Jonathan, I see your point. But I'd rather that we, as a project, strive to make our header files good tables of contents of the publicly-accessible functionality, including decent documentation for each function. I try to add comments to everything I touch, and I wish other developers would too. [What we really need is a comment fascist who patrols patch submissions making sure that they add docstrings for new functions. If I only had the time and the jackboots for it...] So I'd rather leave the comments for public functions in the header files. But if other regular developers prefer that comments be by the function definitions, of course I can live with that, too. Michael -- Michael Haggerty mhag...@alum.mit.edu -- 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
