summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDan McGee <dan@archlinux.org>2007-03-29 00:40:49 -0400
committerDan McGee <dan@archlinux.org>2007-03-29 00:40:49 -0400
commitbbe55b5ce9f5c43e1c9d5e7e326429175b207ba0 (patch)
tree82b151aef7d9bfec33f7a046b2d69a7cf70106c4
parent462ad153e7405013aace5473602e07728d55c278 (diff)
downloadpacman-bbe55b5ce9f5c43e1c9d5e7e326429175b207ba0.tar.xz
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>
-rw-r--r--lib/libalpm/Doxyfile116
-rw-r--r--lib/libalpm/alpm.c7
-rw-r--r--lib/libalpm/alpm.h1
-rw-r--r--lib/libalpm/alpm_list.c239
-rw-r--r--lib/libalpm/alpm_list.h20
5 files changed, 287 insertions, 96 deletions
diff --git a/lib/libalpm/Doxyfile b/lib/libalpm/Doxyfile
index c0b98ad5..240794da 100644
--- a/lib/libalpm/Doxyfile
+++ b/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_CLASSES = YES
+HIDE_UNDOC_MEMBERS = NO
+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 =
-FILE_PATTERNS = *.c
+INPUT = alpm.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_FILE_PATTERNS =
-PREDEFINED =
+INCLUDE_PATH = ../..
+INCLUDE_FILE_PATTERNS = *.h
+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
diff --git a/lib/libalpm/alpm.c b/lib/libalpm/alpm.c
index 48044bad..1678fd32 100644
--- a/lib/libalpm/alpm.c
+++ b/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
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index fc4aed59..954cf96f 100644
--- a/lib/libalpm/alpm.h
+++ b/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/"
diff --git a/lib/libalpm/alpm_list.c b/lib/libalpm/alpm_list.c
index 54027455..0f05df8a 100644
--- a/lib/libalpm/alpm_list.c
+++ b/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
- * @param fn a free function for the internal data
+/**
+ * @brief Free the internal data of a list structure.
+ *
+ * @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
- * @param data the new item to be added to the list
- * @return the resultant list, or NULL on failure
+/**
+ * @brief Add a new item to the list.
+ *
+ * @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
- * @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, or NULL on failure
+/**
+ * @brief Add items to a list in sorted order.
+ *
+ * @param list the list to add to
+ * @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
- * @param n the size of the list
- * @param fn the comparison function for determining order
+/**
+ * @brief Sort a list of size `n` using mergesort algorithm.
+ *
+ * @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
- * @param needle the data member of the item we're removing
- * @param fn the comparison function for searching
- * @param data output parameter containing the data member of the item removed
- * @return the resultant list, or NULL on failure
+/**
+ * @brief Remove an item from the list.
+ *
+ * @param haystack the list to remove the item from
+ * @param needle the data member of the item we're removing
+ * @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
- * @param node the list node we're removing
- * @return the node which took the place of this one
+/**
+ * @brief Remove the node from the list that it belongs to.
+ *
+ * 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
- * @param list the list to copy
- * @return a NEW list containing non-duplicated items
+/**
+ * @brief Create a new list without any duplicates.
+ *
+ * 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
- * @param list the list to copy
- * @return a copy of the original list
+/**
+ * @brief Copy a string list, including data.
+ *
+ * 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
- * @return a NEW list in reverse order of the first
+/**
+ * @brief Create a new list in reverse order.
+ *
+ * @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
- * @param n the index of the item to find
- * @return an alpm_list_t node for index `n`
+/**
+ * @brief Return nth element from list (starting from 0).
+ *
+ * @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);
- return(entry->data);
+ if(node == NULL) return(NULL);
+ return(node->data);
}
/* Misc */
-/** Count the list items
- * @param list the list to operate on
- * @return the number of list items
+/**
+ * @brief Get the number of items in a list.
+ *
+ * @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)
- * @param haystack the list to search
- * @return 1 if `needle` is found, 0 otherwise
+/**
+ * @brief Find an item in a list.
+ *
+ * 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
-*/
-/** Is a _string_ in the list (optimization of alpm_list_find for strings)
- * @param needle the string to compare
- * @param haystack the list to search
- * @return 1 if `needle` is found, 0 otherwise
+/**
+ * @brief Find a string in a list.
+ * Optimization of alpm_list_find for strings.
+ *
+ * @param needle the string to search for
+ * @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`
- * @note Entries are not duplicated
+/**
+ * @brief Find the items in list `lhs` that are not present in list `rhs`.
+ *
+ * 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
- * @return a list containing all items in lhs not present in rhs
+ * @param fn the comparison function
+ *
+ * @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)
{
diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h
index 214deea4..838bd775 100644
--- a/lib/libalpm/alpm_list.h
+++ b/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: */