On Sun, Apr 17, 2011 at 7:01 AM, Rémy Oudompheng <[email protected]> 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
