From: Michael Haggerty <mhagger@alum.mit.edu>
Date: Tue, 25 Feb 2014 15:23:26 GMT
Subject: Re: [PATCH 5/6] Document a bunch of functions defined in sha1_file.c
Message-ID: <530CB56E.9020703@alum.mit.edu>
In-Reply-To: <20140224200855.GI7855@google.com>

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