[pacman-dev] [PATCH 2/2] Document API changes for pacman-3.5 release

[Dan McGee]

On Tue, Mar 1, 2011 at 1:25 AM, Rémy Oudompheng
<remyoudompheng at gmail.com> wrote:
> On 2011/2/28 Dan McGee <dpmcgee at gmail.com> wrote:
>> On Mon, Feb 28, 2011 at 4:02 PM, Rémy Oudompheng
>> <remyoudompheng at gmail.com> wrote:
>>> Would you approve documenting in alpm.h the type of elements in lists
>>> returned by libalpm functions ? They do not look obvious at all for
>>> someone that is not familiar with the internals of libalpm.
>>
>> Definitely. If you can do it in Doxygen style that would be a step in
>> the right direction too, since we could eventually get autogenerated
>> docs and manpages, but baby steps.
>
> Do we want to put any documentation in alpm.h or would it better to
> have Doxygen style only in the source code, documenting the public API
> ?
Both? And maybe doxygen doesn't belong in alpm.h, but it surely
deserves some more documentation than it has. Compare our header to
something more carefully constructed such as /usr/include/archive.h.

> I hesitate between two approaches : I see a use of Doxygen groups
> (with the @addtogroup command) but sometimes, it seems very natural to
> use an object-oriented style. For example, we could document
> alpm_pkg_get_depends() as
>
> /**
>  * Returns a reference to the list of package dependencies.
>  * @public @memberof pmpkg_t
>  * @return a pointer to a list of pmdepend_t structures.
>  */
> alpm_list_t *alpm_pkg_get_depends(pmpkg_t *pkg);
>
> So that it shows on a page dedicated to pmpkg_t.

I'll tell you what- you present an approach that works once you've
documented enough things- I think the question will answer itself
better then and I'm more than happy to let the person that does the
work bake the cake on this decision.

-Dan