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.


Michael Haggerty

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

Reply via email to