Doxygen fixups for libalpm

We haven't done a whole lot with Doxygen so far, so this updates some of the
things that have changed a lot- namely, the now public exposure of alpm_list.
All functions in this file have now been Doxygen commented, and a few other
things in alpm.c were fixed as well. In addition, the Doxygen config file
was updated.

Signed-off-by: Dan McGee <dan@archlinux.org>

lib/libalpm/Doxyfile

@@ -1,11 +1,11 @@
-# Doxyfile 1.4.5
+# Doxyfile 1.5.1
 
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
 PROJECT_NAME           = libalpm
 PROJECT_NUMBER         = 
-OUTPUT_DIRECTORY       = 
+OUTPUT_DIRECTORY       = ../../doc
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 USE_WINDOWS_ENCODING   = NO
@@ -22,7 +22,7 @@ ABBREVIATE_BRIEF       = "The $name class" \
                          a \
                          an \
                          the
-ALWAYS_DETAILED_SEC    = NO
+ALWAYS_DETAILED_SEC    = YES
 INLINE_INHERITED_MEMB  = NO
 FULL_PATH_NAMES        = YES
 STRIP_FROM_PATH        = 
@@ -33,7 +33,7 @@ MULTILINE_CPP_IS_BRIEF = NO
 DETAILS_AT_TOP         = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 8
+TAB_SIZE               = 4
 ALIASES                = 
 OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
@@ -48,10 +48,10 @@ EXTRACT_PRIVATE        = NO
 EXTRACT_STATIC         = NO
 EXTRACT_LOCAL_CLASSES  = YES
 EXTRACT_LOCAL_METHODS  = NO
-HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = YES
+HIDE_UNDOC_CLASSES     = NO
 HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = NO
+HIDE_IN_BODY_DOCS      = YES
 INTERNAL_DOCS          = NO
 CASE_SENSE_NAMES       = YES
 HIDE_SCOPE_NAMES       = NO
@@ -82,8 +82,11 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = 
+INPUT                  = alpm.c \
-FILE_PATTERNS          = *.c
+                         alpm.h \
+                         alpm_list.c \
+                         alpm_list.h
+FILE_PATTERNS          = 
 RECURSIVE              = NO
 EXCLUDE                = 
 EXCLUDE_SYMLINKS       = NO
@@ -99,37 +102,89 @@ FILTER_SOURCE_FILES    = NO
 # configuration options related to source browsing
 #---------------------------------------------------------------------------
 SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
 #---------------------------------------------------------------------------
 # configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output
 #---------------------------------------------------------------------------
 GENERATE_HTML          = NO
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = 
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
 #---------------------------------------------------------------------------
 # configuration options related to the LaTeX output
 #---------------------------------------------------------------------------
 GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = NO
+USE_PDFLATEX           = NO
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
 #---------------------------------------------------------------------------
 # configuration options related to the RTF output
 #---------------------------------------------------------------------------
 GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
 #---------------------------------------------------------------------------
 # configuration options related to the man page output
 #---------------------------------------------------------------------------
 GENERATE_MAN           = YES
-MAN_OUTPUT             = ../../doc
+MAN_OUTPUT             = .
 MAN_EXTENSION          = .3
 MAN_LINKS              = YES
 #---------------------------------------------------------------------------
 # configuration options related to the XML output
 #---------------------------------------------------------------------------
 GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
 #---------------------------------------------------------------------------
 # configuration options related to the Perl module output
 #---------------------------------------------------------------------------
 GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
 #---------------------------------------------------------------------------
 # Configuration options related to the preprocessor   
 #---------------------------------------------------------------------------
@@ -137,12 +192,47 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = NO
 EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
+INCLUDE_PATH           = ../..
-INCLUDE_FILE_PATTERNS  = 
+INCLUDE_FILE_PATTERNS  = *.h
-PREDEFINED             = 
+PREDEFINED             = HAVE_CONFIG_H
 EXPAND_AS_DEFINED      = 
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
 # Configuration options related to the dot tool   
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = NO
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+MAX_DOT_GRAPH_WIDTH    = 1024
+MAX_DOT_GRAPH_HEIGHT   = 1024
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO

lib/libalpm/alpm.c

@@ -564,6 +564,13 @@ static char *_supported_archs[] = {
 	"x86_64",
 };
 
+/**
+ * @brief Determine if a package name has -ARCH tacked on.
+ *
+ * @param pkgname name of the package to parse
+ *
+ * @return pointer to start of -ARCH text if it exists, else NULL
+ */
 char SYMEXPORT *alpm_pkg_name_hasarch(char *pkgname)
 {
 	/* TODO remove this when we transfer everything over to -ARCH

lib/libalpm/alpm.h

@@ -34,6 +34,7 @@ extern "C" {
  * Arch Linux Package Management library
  */
 
+/* TODO these should all be defined in config.h */
 #define PM_ROOT     "/"
 #define PM_DBPATH   "var/lib/pacman/"
 #define PM_CACHEDIR "var/cache/pacman/pkg/"

lib/libalpm/alpm_list.c

@@ -29,13 +29,22 @@
 #include "alpm_list.h"
 #include "util.h"
 
-/** \defgroup alpm_list functions */
+/**
-/*\@{*/
+ * @addtogroup alpm_list List Functions
+ * @brief Functions to manipulate alpm_list_t lists.
+ *
+ * These functions are designed to create, destroy, and modify lists of
+ * type alpm_list_t. This is an internal list type used by libalpm that is
+ * publicly exposed for use by frontends if desired.
+ *
+ * @{ */
 
 /* Allocation */
 
-/** Allocate a new alpm_list_t
+/**
- *  @return a new alpm_list_t item, or NULL on failure
+ * @brief Allocate a new alpm_list_t.
+ *
+ * @return a new alpm_list_t item, or NULL on failure
  */
 alpm_list_t *alpm_list_new()
 {
@@ -47,11 +56,14 @@ alpm_list_t *alpm_list_new()
 		list->prev = NULL;
 		list->next = NULL;
 	}
+
 	return(list);
 }
 
-/** Free a list, but not the contained data
+/**
- *  @param list the list to free
+ * @brief Free a list, but not the contained data.
+ *
+ * @param list the list to free
  */
 void SYMEXPORT alpm_list_free(alpm_list_t *list)
 {
@@ -64,9 +76,11 @@ void SYMEXPORT alpm_list_free(alpm_list_t *list)
 	}
 }
 
-/** Free the internal data of a list structure
+/**
- *  @param list the list to free
+ * @brief Free the internal data of a list structure.
- *  @param fn a free function for the internal data
+ *
+ * @param list the list to free
+ * @param fn   a free function for the internal data
  */
 void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn)
 {
@@ -83,10 +97,13 @@ void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn)
 
 /* Mutators */
 
-/** Add a new item to the list
+/**
- *  @param list the list to add to
+ * @brief Add a new item to the list.
- *  @param data the new item to be added to the list
+ *
- *  @return the resultant list, or NULL on failure
+ * @param list the list to add to
+ * @param data the new item to be added to the list
+ *
+ * @return the resultant list
  */
 alpm_list_t SYMEXPORT *alpm_list_add(alpm_list_t *list, void *data)
 {
@@ -117,11 +134,14 @@ alpm_list_t SYMEXPORT *alpm_list_add(alpm_list_t *list, void *data)
 	return(ptr);
 }
 
-/** Add items to a list in sorted order.
+/**
- *  @param list the list to add to
+ * @brief Add items to a list in sorted order.
- *  @param data the new item to be added to the list
+ *
- *  @param fn the comparison function to use to determine order
+ * @param list the list to add to
- *  @return the resultant list, or NULL on failure
+ * @param data the new item to be added to the list
+ * @param fn   the comparison function to use to determine order
+ *
+ * @return the resultant list
  */
 alpm_list_t *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn)
 {
@@ -158,10 +178,14 @@ alpm_list_t *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cm
 	}
 }
 
-/** Merge the two sorted sublists into one sorted list
+/**
- * @param left the first list
+ * @brief Merge the two sorted sublists into one sorted list.
+ *
+ * @param left  the first list
  * @param right the second list
- * @param fn comparison function for determining merge order
+ * @param fn    comparison function for determining merge order
+ *
+ * @return the resultant list
  */
 alpm_list_t *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right, alpm_list_fn_cmp fn)
 {
@@ -209,10 +233,14 @@ alpm_list_t *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right, alpm_list_f
 	return(newlist);
 }
 
-/** Sort a list of size `n` using mergesort algorithm
+/**
- *  @param list the list to sort
+ * @brief Sort a list of size `n` using mergesort algorithm.
- *  @param n the size of the list
+ *
- *  @param fn the comparison function for determining order
+ * @param list the list to sort
+ * @param n    the size of the list
+ * @param fn   the comparison function for determining order
+ *
+ * @return the resultant list
  */
 alpm_list_t* alpm_list_msort(alpm_list_t *list, int n, alpm_list_fn_cmp fn)
 {
@@ -230,12 +258,15 @@ alpm_list_t* alpm_list_msort(alpm_list_t *list, int n, alpm_list_fn_cmp fn)
 	return(list);
 }
 
-/** Remove an item from the list
+/**
- *  @param haystack the list to remove the item from
+ * @brief Remove an item from the list.
- *  @param needle the data member of the item we're removing
+ *
- *  @param fn the comparison function for searching
+ * @param haystack the list to remove the item from
- *  @param data output parameter containing the data member of the item removed
+ * @param needle   the data member of the item we're removing
- *  @return the resultant list, or NULL on failure
+ * @param fn       the comparison function for searching
+ * @param data     output parameter containing data of the removed item
+ *
+ * @return the resultant list
  */
 alpm_list_t *alpm_list_remove(alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn, void **data)
 { /* TODO I modified this to remove ALL matching items.  Do we need a remove_first? */
@@ -276,10 +307,14 @@ alpm_list_t *alpm_list_remove(alpm_list_t *haystack, const void *needle, alpm_li
 	return(haystack);
 }
 
-/** Remove the passed in node from the list that it is a part of
+/**
- *  @note this DOES NOT free the node
+ * @brief Remove the node from the list that it belongs to.
- *  @param node the list node we're removing
+ *
- *  @return the node which took the place of this one
+ * This DOES NOT free the node.
+ *
+ * @param node the list node we're removing
+ *
+ * @return the node which took the place of this one
  */
 alpm_list_t *alpm_list_remove_node(alpm_list_t *node)
 {
@@ -301,10 +336,14 @@ alpm_list_t *alpm_list_remove_node(alpm_list_t *node)
 	return(ret);
 }
 
-/** Create a new list without any duplicates
+/**
- *  @note DOES NOT copy data members
+ * @brief Create a new list without any duplicates.
- *  @param list the list to copy
+ *
- *  @return a NEW list containing non-duplicated items
+ * This does NOT copy data members.
+ *
+ * @param list the list to copy
+ *
+ * @return a new list containing non-duplicate items
  */
 alpm_list_t SYMEXPORT *alpm_list_remove_dupes(alpm_list_t *list)
 { /* TODO does removing the strdup here cause invalid free's anywhere? */
@@ -318,10 +357,14 @@ alpm_list_t SYMEXPORT *alpm_list_remove_dupes(alpm_list_t *list)
 	return(newlist);
 }
 
-/** Copy a string list, including data
+/**
- *  @note this is gross, assumes string data members
+ * @brief Copy a string list, including data.
- *  @param list the list to copy
+ * 
- *  @return a copy of the original list
+ * This is gross, assumes string data members.
+ *
+ * @param list the list to copy
+ *
+ * @return a copy of the original list
  */
 alpm_list_t *alpm_list_strdup(alpm_list_t *list)
 {
@@ -333,9 +376,12 @@ alpm_list_t *alpm_list_strdup(alpm_list_t *list)
 	return(newlist);
 }
 
-/** Create a new list in reverse order
+/**
- *  @param list the list to copy
+ * @brief Create a new list in reverse order.
- *  @return a NEW list in reverse order of the first
+ *
+ * @param list the list to copy
+ *
+ * @return a new list in reverse order
  */
 alpm_list_t *alpm_list_reverse(alpm_list_t *list)
 { /* TODO any invalid free's from NOT duplicating data here? */
@@ -351,8 +397,11 @@ alpm_list_t *alpm_list_reverse(alpm_list_t *list)
 
 /* Accessors */
 
-/** Get the first element of a list.
+/**
+ * @brief Get the first element of a list.
+ *
  * @param list the list
+ *
  * @return the first element in the list
  */
 alpm_list_t SYMEXPORT *alpm_list_first(alpm_list_t *list)
@@ -360,10 +409,13 @@ alpm_list_t SYMEXPORT *alpm_list_first(alpm_list_t *list)
 	return(list);
 }
 
-/** Return nth element from list (starting with 0)
+/**
- *  @param list the list to access
+ * @brief Return nth element from list (starting from 0).
- *  @param n the index of the item to find
+ *
- *  @return an alpm_list_t node for index `n`
+ * @param list the list
+ * @param n    the index of the item to find
+ *
+ * @return an alpm_list_t node for index `n`
  */
 alpm_list_t *alpm_list_nth(alpm_list_t *list, int n)
 {
@@ -374,17 +426,24 @@ alpm_list_t *alpm_list_nth(alpm_list_t *list, int n)
 	return(i);
 }
 
-/** Get the next element of a list.
+/**
- * @param entry the list entry
+ * @brief Get the next element of a list.
+ *
+ * @param node the list node
+ *
  * @return the next element, or NULL when no more elements exist
  */
-alpm_list_t SYMEXPORT *alpm_list_next(alpm_list_t *entry)
+inline alpm_list_t SYMEXPORT *alpm_list_next(alpm_list_t *node)
 {
-	return(entry->next);
+	return(node->next);
 }
-/** Get the last item in the list.
+
- *  @param list the list to operate on
+/**
- *  @return the last element in the list
+ * @brief Get the last item in the list.
+ *
+ * @param list the list
+ *
+ * @return the last element in the list
  */
 alpm_list_t *alpm_list_last(alpm_list_t *list)
 {
@@ -395,21 +454,27 @@ alpm_list_t *alpm_list_last(alpm_list_t *list)
 	return(i);
 }
 
-/** Get the data member of a list entry.
+/**
- * @param entry the list entry
+ * @brief Get the data member of a list node.
+ *
+ * @param node the list node
+ *
  * @return the contained data, or NULL if none
  */
-void SYMEXPORT *alpm_list_getdata(const alpm_list_t *entry)
+void SYMEXPORT *alpm_list_getdata(const alpm_list_t *node)
 {
-	if(entry == NULL) return(NULL);
+	if(node == NULL) return(NULL);
-	return(entry->data);
+	return(node->data);
 }
 
 /* Misc */
 
-/** Count the list items
+/**
- *  @param list the list to operate on
+ * @brief Get the number of items in a list.
- *  @return the number of list items
+ *
+ * @param list the list
+ *
+ * @return the number of list items
  */
 int SYMEXPORT alpm_list_count(const alpm_list_t *list)
 {
@@ -422,10 +487,15 @@ int SYMEXPORT alpm_list_count(const alpm_list_t *list)
 	return(i);
 }
 
-/** Is an item in the list
+/**
- *  @param needle the data to compare to (== comparison)
+ * @brief Find an item in a list.
- *  @param haystack the list to search
+ * 
- *  @return 1 if `needle` is found, 0 otherwise
+ * Search for the item whos data matches that of the `needle`.
+ *
+ * @param needle   the data to search for (== comparison)
+ * @param haystack the list
+ *
+ * @return 1 if `needle` is found, 0 otherwise
  */
 int SYMEXPORT alpm_list_find(alpm_list_t *haystack, const void *needle)
 {
@@ -439,12 +509,14 @@ int SYMEXPORT alpm_list_find(alpm_list_t *haystack, const void *needle)
 	return(0);
 }
 
-/* Test for existence of a string in a alpm_list_t
+/**
-*/
+ * @brief Find a string in a list.
-/** Is a _string_ in the list (optimization of alpm_list_find for strings)
+ *        Optimization of alpm_list_find for strings.
- *  @param needle the string to compare
+ *
- *  @param haystack the list to search
+ * @param needle   the string to search for
- *  @return 1 if `needle` is found, 0 otherwise
+ * @param haystack the list
+ *
+ * @return 1 if `needle` is found, 0 otherwise
  */
 int SYMEXPORT alpm_list_find_str(alpm_list_t *haystack, const char *needle)
 {
@@ -458,13 +530,18 @@ int SYMEXPORT alpm_list_find_str(alpm_list_t *haystack, const char *needle)
 	return(0);
 }
 
-/** 
+/**
- * Calculate the items in list `lhs` that are not present in list `rhs`
+ * @brief Find the items in list `lhs` that are not present in list `rhs`.
- * @note Entries are not duplicated
+ *
+ * Entries are not duplicated. Operation is O(m*n). The first list is stepped
+ * through one node at a time, and for each node in the first list, each node
+ * in the second list is compared to it.
+ *
  * @param lhs the first list
  * @param rhs the second list
- * @param fn the comparison function
+ * @param fn  the comparison function
- * @return a list containing all items in lhs not present in rhs
+ *
+ * @return a list containing all items in `lhs` not present in `rhs`
  */
 alpm_list_t *alpm_list_diff(alpm_list_t *lhs, alpm_list_t *rhs, alpm_list_fn_cmp fn)
 {

lib/libalpm/alpm_list.h

@@ -1,5 +1,5 @@
 /*
- *  alpm_alpm_list.h
+ *  alpm_list.h
  * 
  *  Copyright (c) 2002-2006 by Judd Vinet <jvinet@zeroflux.org>
  * 
@@ -21,12 +21,25 @@
 #ifndef _ALPM_LIST_H
 #define _ALPM_LIST_H
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #include "alpm.h"
 
-/* Chained list struct */
+/**
+ * @brief Linked list type used by libalpm.
+ *
+ * It is exposed so front ends can use it to prevent the need to reimplement
+ * lists of their own; however, it is not required that the front end uses
+ * it.
+ */
 struct __alpm_list_t {
+	/** data held by the list node */
 	void *data;
+	/** pointer to the previous node */
 	struct __alpm_list_t *prev;
+	/** pointer to the next node */
 	struct __alpm_list_t *next;
 };
 
@@ -67,6 +80,9 @@ int alpm_list_find(alpm_list_t *haystack, const void *needle);
 int alpm_list_find_str(alpm_list_t *haystack,const char *needle);
 alpm_list_t *alpm_list_diff(alpm_list_t *lhs, alpm_list_t *rhs, alpm_list_fn_cmp fn);
 
+#ifdef __cplusplus
+}
+#endif
 #endif /* _ALPM_LIST_H */
 
 /* vim: set ts=2 sw=2 noet: */