diff options
| -rw-r--r-- | lib/libalpm/Doxyfile | 116 | ||||
| -rw-r--r-- | lib/libalpm/alpm.c | 7 | ||||
| -rw-r--r-- | lib/libalpm/alpm.h | 1 | ||||
| -rw-r--r-- | lib/libalpm/alpm_list.c | 239 | ||||
| -rw-r--r-- | lib/libalpm/alpm_list.h | 20 |
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: */ |