[pacman-dev] [PATCH] alpm.h: add/improve function documentation

[Rémy Oudompheng]

On 2011/4/17 Sebastian Nowicki <sebnow at gmail.com> wrote:
> On Sun, Apr 17, 2011 at 3:48 PM, Rémy Oudompheng <remyoudompheng at gmail.com>
> wrote:
> Does the documentation mention anywhere that pm_errno will be set when
> errors occur (I don't think this is even 100% accurate)? If not, do we
> really want to remove that little bit of info from the documentation? Also I
> find it odd that you're changing the documentation of these two functions,
> but add equivalent documentation to alpm_remove_pkg().

Dan doesn't want to duplicate documentation (and that is, indeed, a
maintenance problem). However, we have to choose between putting
documentation in alpm.h or in source files (for publicly available
functions).

For these functions, a choice was to have fully detailed documentation
in alpm.h, and leave only a small description in the source files.

I don't think that's the right way to do: documentation should be
closest to source code, and doxygen is smart enough to put together
the documentation for each function across the source files and be
able if needed to produce the documentation for the public API only.

Having documentation in the header is indeed a wrong answer to the
fact that we don't have documentation/man pages.

Rémy.