On Tue, Mar 1, 2011 at 1:25 AM, Rémy Oudompheng <[email protected]> wrote: > On 2011/2/28 Dan McGee <[email protected]> wrote: >> On Mon, Feb 28, 2011 at 4:02 PM, Rémy Oudompheng >> <[email protected]> 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
