[pacman-dev] [PATCH 2/2] Document API changes for pacman-3.5 release
dpmcgee at gmail.com
Tue Mar 1 08:17:23 EST 2011
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.
More information about the pacman-dev