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

[Sebastian Nowicki]

On Sun, Apr 17, 2011 at 5:57 PM, Rémy Oudompheng
<remyoudompheng at gmail.com> wrote:
> 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).

If duplication is an issue then there should be a mention of pm_errno
in some generic documentation about the API (I don't think there is
anything like that). This would have to be true for all functions
though (with exceptions being documented). If such "behind the scenes"
error reporting isn't documented it may as well not be implemented.

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

The advantage of documentation in the header files is that the header
files are distributed, thus easily available. Obviously man
pages/generated documentation would be better.