Re: [PATCH 5/6] Document a bunch of functions defined in sha1_file.c

On 02/24/2014 09:08 PM, Jonathan Nieder wrote:

Michael Haggerty wrote:

quoted

[...]  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
mhagger@alum.mit.edu