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