On 2011/4/17 Sebastian Nowicki <sebnow@gmail.com> wrote:
On Sun, Apr 17, 2011 at 3:48 PM, Rémy Oudompheng <remyoudompheng@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.