From: Michael Haggerty <mhagger@alum.mit.edu>
Date: Wed, 10 Dec 2014 20:09:32 GMT
Subject: Re: [PATCH] document string_list_clear
Message-ID: <5488A87C.4030505@alum.mit.edu>
In-Reply-To: <20141210084351.GA29776@peff.net>

My vote is for putting the API docs in the header files:

* Functions are documented right next to their declarations (which the
compiler guarantees are up-to-date), removing ambiguity and avoiding
some redundancy.

* It is obvious at a glance which functions are documented and which
still need docs.

* It is easier to remember to update the documentation when it is near
the code, and easier for reviewers to remember to pester authors to do so.

I also like it when function declarations in header files include the
names of their parameters, as (1) it's an efficient way to give the
reader a good hint about how the function should be used, and (2) it
makes it easier to refer to the parameters from the docstring.

I agree that there is an important need for introductory/conceptual
documentation about and API, but I think this fits fine as a large
docstring at the top of the header file.

I personally don't have much use for formatted documentation but if that
were a need I would think that a standard tool like doxygen could be used.

I have been trying hard to add good header-file docstrings for code that
I have worked on, and even for code that I had to read because I needed
to figure out how to use it. I would find it a pity for that work to be
squashed into Documentation/technical/api-*.txt, where in my opinion it
is less discoverable and more likely to fall into disrepair.

Michael