On Sun, Apr 17, 2011 at 7:01 AM, Rémy Oudompheng <remyoudompheng@gmail.com> wrote:
It is commonly accepted that incorrect documentation is worse than none. Unfortunately commits
6ebb6fec8b356c87e6fdea5659bbf34461adee90 96432ab4ef27bc6a570427736d8b7f439535e05f aac9e7c280a9686520e0f8f4bd7ffe4ed901716d
separated documentation and source code for public, exported functions. This makes maintenance more difficult since behaviour changes require documentation updates in a separate file.
This commit moves them back to source files, but leaves the necessary hints in alpm.h to produce structured output using doxygen.
Hmm. Totally disagree with this rationale. As Sebastian noted in another email [1], we distribute these header files so any documentation in them is a really good thing. Leaving the hints but no docs in alpm.h makes the headers even more confusing to an outsider. I'm not sure I totally see why having the function source and the doc in a different place is that big of problem? You aren't going to have that many maintenance problems, given that if you change a function signature in a code file, you have to update it in the header, which in turn has the documentation right above it. As long as we review patches with this in mind, even changes that would need a doc update but not a signature change we will catch. So my "vote" is to keep this stuff in alpm.h, and ensure when reviewing patches with changes to SYMEXPORT functions we determine if a documentation change is necessary. -Dan [1] http://mailman.archlinux.org/pipermail/pacman-dev/2011-April/012987.html