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 -- 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
