Re: [PATCH] document string_list_clear

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