[pacman-dev] [PATCH 1/2] Move documentation of public API back to source files.

[Dan McGee]

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