The man pages produced by doxygen never quite lived up to expectation, and it would now be very difficult to get them to fit in with the other man pages produced by asciidoc. So the doc/Makefile.am *_MANS settings are updated to only ever use the ASCIIDOC_MANS. The Doxyfile had grown quite stale, with settings from years back for which the current default values are better. It also specified 242 settings when most of them were at default values (and could thus be omitted - only 23 of the 242 actually accomplished anything). Also the hard-coded INPUT paths prevented VPATH builds. So a new, easier to understand, configured Doxyfile.in takes its place. Doxyfile.in no longer produces man pages, as they were never used. Instead it produces html. And it does so for all the pacman code, not just the libalpm API. Doxygen can optionally use the graphviz 'dot' app to produce more intricate graphs, if configure can find the program (unless --disable-graphviz is specified). The new 'make doxygen-run' and 'make doxygen-clean' targets are always available to invoke manually. If '--enable-doxygen' is passed to configure then 'make all' will invoke doxygen-run. All the doxygen output (the generated files, and logs of the stdout and stderr) is diverted to the 'doc/doxyout' subdir. The doxygen-clean target, which is always invoked by 'make clean', removes this subdir. Signed-off-by: Jeremy Heiner <ScalaProtractor at gmail.com> --- configure.ac | 26 ++++- doc/.gitignore | 3 +- doc/Doxyfile | 305 -------------------------------------------------------- doc/Doxyfile.in | 43 ++++++++ doc/Makefile.am | 27 +++-- 5 files changed, 82 insertions(+), 322 deletions(-) delete mode 100644 doc/Doxyfile create mode 100644 doc/Doxyfile.in diff --git a/configure.ac b/configure.ac index cfcc8d1..c088122 100644 --- a/configure.ac +++ b/configure.ac @@ -145,6 +145,11 @@ AC_ARG_ENABLE(doxygen, AS_HELP_STRING([--enable-doxygen], [build your own API docs via Doxygen]), [wantdoxygen=$enableval], [wantdoxygen=no]) +# Help line for graphviz (optionally used by doxygen) +AC_ARG_ENABLE(graphviz, + AS_HELP_STRING([--disable-graphviz], [prevent doxygen from using dot]), + [wantgraphviz=$enableval], [wantgraphviz=yes]) + # Help line for debug AC_ARG_ENABLE(debug, AS_HELP_STRING([--enable-debug], [enable debugging support]), @@ -381,7 +386,7 @@ AM_CONDITIONAL(WANT_DOC, test "x$wantdoc" = "xyes") # Check for doxygen support and status AC_CHECK_PROGS([DOXYGEN], [doxygen]) -AC_MSG_CHECKING([for doxygen]) +AC_MSG_CHECKING([whether 'make all' should 'make doxygen-run']) if test "x$wantdoxygen" = "xyes" ; then if test $DOXYGEN ; then AC_MSG_RESULT([yes]) @@ -396,6 +401,23 @@ else fi AM_CONDITIONAL(USE_DOXYGEN, test "x$usedoxygen" = "xyes") +# Optionally doxygen can use dot +AC_CHECK_PROGS([GRAPHVIZDOT], [dot]) +AC_MSG_CHECKING([whether doxygen should use graphviz]) +if test "x$wantgraphviz" = "xyes" ; then + if test $GRAPHVIZDOT ; then + AC_MSG_RESULT([yes]) + usegraphviz=yes + else + AC_MSG_RESULT([no, graphviz missing]) + usegraphviz=no + fi +else + AC_MSG_RESULT([no, disabled by configure]) + usegraphviz=no +fi +AC_SUBST(HAVE_DOT,`echo $usegraphviz | tr yesno YESNO`) + # Enable or disable debug code AC_MSG_CHECKING(for debug mode request) if test "x$debug" = "xyes" ; then @@ -498,6 +520,7 @@ src/pacman/po/Makefile.in src/util/Makefile scripts/Makefile scripts/po/Makefile.in +doc/Doxyfile doc/Makefile etc/Makefile test/pacman/Makefile @@ -551,6 +574,7 @@ ${PACKAGE_NAME}: Use OpenSSL : ${have_openssl} Run make in doc/ dir : ${wantdoc} ${asciidoc} Doxygen support : ${usedoxygen} + use graphviz dot : ${usegraphviz} debug support : ${debug} extra warning flags : ${warningflags} use git version : ${wantgitver} diff --git a/doc/.gitignore b/doc/.gitignore index ad496ce..7032f6e 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -16,5 +16,6 @@ asciidoc.css asciidoc.js *.html *.xml -man3 +Doxyfile +doxyout/ website.tar.gz diff --git a/doc/Doxyfile b/doc/Doxyfile deleted file mode 100644 index 4e64534..0000000 --- a/doc/Doxyfile +++ /dev/null @@ -1,305 +0,0 @@ -# Doxyfile 1.8.2 - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = libalpm -PROJECT_NUMBER = -PROJECT_BRIEF = "Arch Linux Package Manager Library" -PROJECT_LOGO = -OUTPUT_DIRECTORY = ./ -CREATE_SUBDIRS = NO -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = "The $name class" \ - "The $name widget" \ - "The $name file" \ - is \ - provides \ - specifies \ - contains \ - represents \ - a \ - an \ - the -ALWAYS_DETAILED_SEC = YES -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = NO -STRIP_FROM_PATH = -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES -QT_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = NO -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 4 -ALIASES = -TCL_SUBST = -OPTIMIZE_OUTPUT_FOR_C = YES -OPTIMIZE_OUTPUT_JAVA = NO -OPTIMIZE_FOR_FORTRAN = NO -OPTIMIZE_OUTPUT_VHDL = NO -EXTENSION_MAPPING = -MARKDOWN_SUPPORT = YES -AUTOLINK_SUPPORT = YES -BUILTIN_STL_SUPPORT = NO -CPP_CLI_SUPPORT = NO -SIP_SUPPORT = NO -IDL_PROPERTY_SUPPORT = YES -DISTRIBUTE_GROUP_DOC = NO -SUBGROUPING = YES -INLINE_GROUPED_CLASSES = NO -INLINE_SIMPLE_STRUCTS = NO -TYPEDEF_HIDES_STRUCT = NO -SYMBOL_CACHE_SIZE = 0 -LOOKUP_CACHE_SIZE = 0 -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -EXTRACT_PACKAGE = NO -EXTRACT_STATIC = NO -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -EXTRACT_ANON_NSPACES = NO -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = YES -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = YES -HIDE_SCOPE_NAMES = NO -SHOW_INCLUDE_FILES = YES -FORCE_LOCAL_INCLUDES = NO -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = NO -SORT_MEMBERS_CTORS_1ST = NO -SORT_GROUP_NAMES = NO -SORT_BY_SCOPE_NAME = NO -STRICT_PROTO_MATCHING = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_FILES = YES -SHOW_NAMESPACES = YES -FILE_VERSION_FILTER = -LAYOUT_FILE = -CITE_BIB_FILES = -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- -INPUT = ../lib/libalpm/ -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = -RECURSIVE = NO -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = * -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -FILTER_SOURCE_PATTERNS = -#--------------------------------------------------------------------------- -# 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_EXTRA_STYLESHEET = -HTML_EXTRA_FILES = -HTML_COLORSTYLE_HUE = 220 -HTML_COLORSTYLE_SAT = 100 -HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = YES -HTML_DYNAMIC_SECTIONS = NO -HTML_INDEX_NUM_ENTRIES = 100 -GENERATE_DOCSET = NO -DOCSET_FEEDNAME = "Doxygen generated docs" -DOCSET_BUNDLE_ID = org.doxygen.Project -DOCSET_PUBLISHER_ID = org.doxygen.Publisher -DOCSET_PUBLISHER_NAME = Publisher -GENERATE_HTMLHELP = NO -CHM_FILE = -HHC_LOCATION = -GENERATE_CHI = NO -CHM_INDEX_ENCODING = -BINARY_TOC = NO -TOC_EXPAND = NO -GENERATE_QHP = NO -QCH_FILE = -QHP_NAMESPACE = org.doxygen.Project -QHP_VIRTUAL_FOLDER = doc -QHP_CUST_FILTER_NAME = -QHP_CUST_FILTER_ATTRS = -QHP_SECT_FILTER_ATTRS = -QHG_LOCATION = -GENERATE_ECLIPSEHELP = NO -ECLIPSE_DOC_ID = org.doxygen.Project -DISABLE_INDEX = NO -GENERATE_TREEVIEW = NO -ENUM_VALUES_PER_LINE = 4 -TREEVIEW_WIDTH = 250 -EXT_LINKS_IN_WINDOW = NO -FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES -USE_MATHJAX = NO -MATHJAX_RELPATH = http://www.mathjax.org/mathjax -MATHJAX_EXTENSIONS = -SEARCHENGINE = NO -SERVER_BASED_SEARCH = NO -#--------------------------------------------------------------------------- -# 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 = letter -EXTRA_PACKAGES = -LATEX_HEADER = -LATEX_FOOTER = -PDF_HYPERLINKS = NO -USE_PDFLATEX = NO -LATEX_BATCHMODE = NO -LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO -LATEX_BIB_STYLE = plain -#--------------------------------------------------------------------------- -# 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 = . -MAN_EXTENSION = .3 -MAN_LINKS = NO -#--------------------------------------------------------------------------- -# 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 -#--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -SEARCH_INCLUDES = YES -INCLUDE_PATH = ../.. -INCLUDE_FILE_PATTERNS = *.h -PREDEFINED = HAVE_CONFIG_H= \ - SYMHIDDEN= \ - SYMEXPORT= \ - HAVE_LIBARCHIVE \ - HAVE_LIBCURL \ - HAVE_LIBGPGME -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 -MSCGEN_PATH = -HIDE_UNDOC_RELATIONS = YES -HAVE_DOT = YES -DOT_NUM_THREADS = 0 -DOT_FONTNAME = Helvetica -DOT_FONTSIZE = 10 -DOT_FONTPATH = -CLASS_GRAPH = YES -COLLABORATION_GRAPH = YES -GROUP_GRAPHS = YES -UML_LOOK = NO -UML_LIMIT_NUM_FIELDS = 10 -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 -INTERACTIVE_SVG = NO -DOT_PATH = -DOTFILE_DIRS = -MSCFILE_DIRS = -DOT_GRAPH_MAX_NODES = 50 -MAX_DOT_GRAPH_DEPTH = 3 -DOT_TRANSPARENT = NO -DOT_MULTI_TARGETS = NO -GENERATE_LEGEND = YES -DOT_CLEANUP = YES diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in new file mode 100644 index 0000000..6250ec5 --- /dev/null +++ b/doc/Doxyfile.in @@ -0,0 +1,43 @@ + +# @configure_input@ + +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "Arch Linux Package Manager" + +INPUT = @top_srcdir@/lib/libalpm \ + @top_srcdir@/src/pacman \ + @top_srcdir@/src/util \ + @top_srcdir@/test/pacman + +STRIP_FROM_PATH = @top_srcdir@/ + +OPTIMIZE_OUTPUT_FOR_C = YES +TYPEDEF_HIDES_STRUCT = YES +JAVADOC_AUTOBRIEF = YES + +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES + +PREDEFINED = HAVE_LIBCURL HAVE_LIBGPGME SYMEXPORT= + +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +INTERNAL_DOCS = YES + +OUTPUT_DIRECTORY = doxyout + +GENERATE_LATEX = NO + +GENERATE_HTML = YES +DISABLE_INDEX = YES +GENERATE_TREEVIEW = YES +HTML_DYNAMIC_SECTIONS = YES + +SOURCE_BROWSER = YES +REFERENCES_RELATION = YES +REFERENCED_BY_RELATION = YES + +HAVE_DOT = @HAVE_DOT@ + diff --git a/doc/Makefile.am b/doc/Makefile.am index cb01255..7f284b8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,7 +1,6 @@ # We have to do some funny stuff here with the manpages. In order to ensure # a dist tarball doesn't get put out there without manpages, we keep those -# files listed in EXTRA_DIST no matter what. However, we only add them to -# man_MANS if --enable-asciidoc and/or --enable-doxygen are used. +# files listed in EXTRA_DIST no matter what. ASCIIDOC_MANS = \ pacman.8 \ @@ -17,8 +16,6 @@ ASCIIDOC_MANS = \ pacman.conf.5 \ libalpm.3 -DOXYGEN_MANS = $(wildcard man3/*.3) - HTML_MANPAGES = \ pacman.8.html \ makepkg.8.html \ @@ -63,9 +60,7 @@ EXTRA_DIST = \ index.txt \ submitting-patches.txt \ translation-help.txt \ - Doxyfile \ - $(ASCIIDOC_MANS) \ - $(DOXYGEN_MANS) + $(ASCIIDOC_MANS) # Files that should be removed, but which Automake does not know. MOSTLYCLEANFILES = *.xml $(ASCIIDOC_MANS) $(HTML_DOCS) repo-remove.8 website.tar.gz @@ -82,23 +77,25 @@ else REAL_PACKAGE_VERSION = $(PACKAGE_VERSION) endif -man_MANS = dist_man_MANS = $(ASCIIDOC_MANS) if USE_DOXYGEN -man_MANS += $(DOXYGEN_MANS) - -all-local: doxygen.in - -doxygen.in: - $(DOXYGEN) $(srcdir)/Doxyfile +all-local: doxygen-run endif +doxygen-run: + mkdir -p doxyout + doxygen 2>&1 >doxyout/doxygen-run.stdout | \ + tee doxyout/doxygen-run.stderr + +clean-local: doxygen-clean +doxygen-clean: + -rm -rf doxyout html: $(HTML_DOCS) website: website.tar.gz -.PHONY: html website +.PHONY: html website doxygen-run doxygen-clean website.tar.gz: html $(AM_V_GEN)bsdtar czf $@ $(HTML_DOCS) \ -- 1.8.5.2

In the recent past only the 2 public .h files were INPUT to doxygen, and so the markup in those 2 files received a little maintenance. But there is also markup in some of the .c files (which the previous commit added back to INPUT) that had not received maintenance. This brings them back into sync. Most notably the ids for the groups in the alpm.h file got changed to "alpm_api_<*>", while the .c files kept "alpm_<*>", causing doxygen to produce two nearly identical copies of those groups. The older .c ids and the @defgroup / @addtogroup @{ @} commands were retired from: {alpm,alpm_list,be_sync,db,delta,log,package,trans,util}.c leaving the group definition solely to the .h files. In alpm_list.h the non-doxygen-markup comments indicating grouping were "upgraded" to be @name @{ @} groups. alpm_list_fn_cmp had to be moved to get it out of the middle of the "allocation" group, which was renamed "deallocation" to be more accurate. In alpm.h an unbalanced @} was found (adding "end group <*>" comments helped). A Signatures group was added. And the alpm_list_t group was moved from being a sibling of the Public API to being a child of it. Signed-off-by: Jeremy Heiner <ScalaProtractor at gmail.com> --- lib/libalpm/alpm.c | 11 ----------- lib/libalpm/alpm.h | 34 ++++++++++++++++++++-------------- lib/libalpm/alpm_list.c | 7 ++----- lib/libalpm/alpm_list.h | 36 ++++++++++++++++++++++++++++++------ lib/libalpm/be_sync.c | 1 - lib/libalpm/db.c | 6 +----- lib/libalpm/delta.c | 7 ------- lib/libalpm/log.c | 5 +---- lib/libalpm/package.c | 5 +---- lib/libalpm/trans.c | 5 +---- lib/libalpm/util.c | 2 -- 11 files changed, 56 insertions(+), 63 deletions(-) diff --git a/lib/libalpm/alpm.c b/lib/libalpm/alpm.c index 878c38b..28d2f06 100644 --- a/lib/libalpm/alpm.c +++ b/lib/libalpm/alpm.c @@ -32,11 +32,6 @@ #include "log.h" #include "util.h" -/** \addtogroup alpm_interface Interface Functions - * @brief Functions to initialize and release libalpm - * @{ - */ - /** Initializes the library. * Creates handle, connects to database and creates lockfile. * This must be called before any other functions are called. @@ -123,12 +118,6 @@ int SYMEXPORT alpm_release(alpm_handle_t *myhandle) return ret; } -/** @} */ - -/** @defgroup alpm_misc Miscellaneous Functions - * @brief Various libalpm functions - */ - /** Get the version of library. * @return the library version, e.g. "6.0.4" * */ diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index e9b0feb..94ad89f 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -598,7 +598,7 @@ int alpm_option_set_local_file_siglevel(alpm_handle_t *handle, alpm_siglevel_t l alpm_siglevel_t alpm_option_get_remote_file_siglevel(alpm_handle_t *handle); int alpm_option_set_remote_file_siglevel(alpm_handle_t *handle, alpm_siglevel_t level); -/** @} */ +/** @} */ /* end group alpm_api_options */ /** @addtogroup alpm_api_databases Database Functions * Functions to query and manipulate the database of libalpm. @@ -731,7 +731,7 @@ int alpm_db_set_usage(alpm_db_t *db, alpm_db_usage_t usage); */ int alpm_db_get_usage(alpm_db_t *db, alpm_db_usage_t *usage); -/** @} */ +/** @} */ /* end group alpm_api_databases */ /** @addtogroup alpm_api_packages Package Functions * Functions to manipulate libalpm packages @@ -1057,8 +1057,7 @@ alpm_list_t *alpm_pkg_unused_deltas(alpm_pkg_t *pkg); int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); -/* End of alpm_pkg */ -/** @} */ +/** @} */ /* end group alpm_api_packages */ /* * Filelists @@ -1074,9 +1073,8 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); */ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); -/* - * Signatures - */ +/** @addtogroup alpm_api_pgp Signatures + * @{ */ int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); @@ -1090,6 +1088,8 @@ int alpm_decode_signature(const char *base64_data, int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, const unsigned char *sig, const size_t len, alpm_list_t **keys); +/** @} */ /* end group alpm_api_pgp */ + /* * Groups */ @@ -1197,7 +1197,8 @@ int alpm_trans_interrupt(alpm_handle_t *handle); * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_release(alpm_handle_t *handle); -/** @} */ + +/** @} */ /* end group alpm_api_trans */ /** @name Common Transactions */ /** @{ */ @@ -1247,9 +1248,7 @@ alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist); */ char *alpm_dep_compute_string(const alpm_depend_t *dep); -/** @} */ - -/** @} */ +/** @} */ /* end group alpm_api_depends */ /* * Helpers @@ -1335,8 +1334,10 @@ alpm_errno_t alpm_errno(alpm_handle_t *handle); /** Returns the string corresponding to an error number. */ const char *alpm_strerror(alpm_errno_t err); -/* End of alpm_api_errors */ -/** @} */ +/** @} */ /* end group alpm_api_errors */ + +/** @name Functions to initialize and release libalpm + * @{ */ alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, alpm_errno_t *err); @@ -1351,9 +1352,14 @@ enum alpm_caps { const char *alpm_version(void); enum alpm_caps alpm_capabilities(void); -/* End of alpm_api */ /** @} */ +/** + * @addtogroup alpm_api_list + * @ingroup alpm_api + */ +/** @} */ /* end group alpm_api */ + #ifdef __cplusplus } #endif diff --git a/lib/libalpm/alpm_list.c b/lib/libalpm/alpm_list.c index a3c73aa..11410d5 100644 --- a/lib/libalpm/alpm_list.c +++ b/lib/libalpm/alpm_list.c @@ -33,14 +33,13 @@ #define SYMHIDDEN __attribute__((visibility("internal"))) /** - * @addtogroup alpm_list List Functions + * @addtogroup alpm_api_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 */ @@ -788,6 +787,4 @@ void SYMEXPORT *alpm_list_to_array(const alpm_list_t *list, size_t n, return array; } -/** @} */ - /* vim: set ts=2 sw=2 noet: */ diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h index 3f3566b..c38c496 100644 --- a/lib/libalpm/alpm_list.h +++ b/lib/libalpm/alpm_list.h @@ -30,6 +30,9 @@ extern "C" { #endif +/** @addtogroup alpm_api_list + * @{ */ + /** * @brief Linked list type used by libalpm. * @@ -46,16 +49,28 @@ typedef struct __alpm_list_t { struct __alpm_list_t *next; } alpm_list_t; +/** + * @brief item comparison callback + */ +typedef int (*alpm_list_fn_cmp)(const void *, const void *); + +/** @name Deallocation + * @{ */ + #define FREELIST(p) do { alpm_list_free_inner(p, free); alpm_list_free(p); p = NULL; } while(0) -typedef void (*alpm_list_fn_free)(void *); /* item deallocation callback */ -typedef int (*alpm_list_fn_cmp)(const void *, const void *); /* item comparison callback */ +/** + * @brief item deallocation callback + */ +typedef void (*alpm_list_fn_free)(void *); -/* allocation */ void alpm_list_free(alpm_list_t *list); void alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn); -/* item mutators */ +/** @} */ +/** @name Mutators + * @{ */ + alpm_list_t *alpm_list_add(alpm_list_t *list, void *data); alpm_list_t *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn); alpm_list_t *alpm_list_join(alpm_list_t *first, alpm_list_t *second); @@ -70,13 +85,19 @@ alpm_list_t *alpm_list_copy(const alpm_list_t *list); alpm_list_t *alpm_list_copy_data(const alpm_list_t *list, size_t size); alpm_list_t *alpm_list_reverse(alpm_list_t *list); -/* item accessors */ +/** @} */ +/** @name Accessors + * @{ */ + alpm_list_t *alpm_list_nth(const alpm_list_t *list, size_t n); alpm_list_t *alpm_list_next(const alpm_list_t *list); alpm_list_t *alpm_list_previous(const alpm_list_t *list); alpm_list_t *alpm_list_last(const alpm_list_t *list); -/* misc */ +/** @} */ +/** @name Misc + * @{ */ + size_t alpm_list_count(const alpm_list_t *list); void *alpm_list_find(const alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn); void *alpm_list_find_ptr(const alpm_list_t *haystack, const void *needle); @@ -86,6 +107,9 @@ void alpm_list_diff_sorted(const alpm_list_t *left, const alpm_list_t *right, alpm_list_fn_cmp fn, alpm_list_t **onlyleft, alpm_list_t **onlyright); void *alpm_list_to_array(const alpm_list_t *list, size_t n, size_t size); +/** @} */ +/** @} */ + #ifdef __cplusplus } #endif diff --git a/lib/libalpm/be_sync.c b/lib/libalpm/be_sync.c index 123d953..de09471 100644 --- a/lib/libalpm/be_sync.c +++ b/lib/libalpm/be_sync.c @@ -158,7 +158,6 @@ valid: * } * @endcode * - * @ingroup alpm_databases * @note After a successful update, the \link alpm_db_get_pkgcache() * package cache \endlink will be invalidated * @param force if true, then forces the update, otherwise update only in case diff --git a/lib/libalpm/db.c b/lib/libalpm/db.c index 2069a7b..35bf2cc 100644 --- a/lib/libalpm/db.c +++ b/lib/libalpm/db.c @@ -37,9 +37,8 @@ #include "package.h" #include "group.h" -/** \addtogroup alpm_databases Database Functions +/** @file * @brief Functions to query and manipulate the database of libalpm - * @{ */ /** Register a sync database of packages. */ @@ -322,9 +321,6 @@ int SYMEXPORT alpm_db_get_usage(alpm_db_t *db, alpm_db_usage_t *usage) return 0; } - -/** @} */ - alpm_db_t *_alpm_db_new(const char *treename, int is_local) { alpm_db_t *db; diff --git a/lib/libalpm/delta.c b/lib/libalpm/delta.c index 2da1496..a8ffc94 100644 --- a/lib/libalpm/delta.c +++ b/lib/libalpm/delta.c @@ -256,11 +256,6 @@ static alpm_list_t *find_unused(alpm_list_t *deltas, const char *to, off_t quota return unused; } -/** \addtogroup alpm_deltas Delta Functions - * @brief Functions to manipulate libalpm deltas - * @{ - */ - alpm_list_t SYMEXPORT *alpm_pkg_unused_deltas(alpm_pkg_t *pkg) { ASSERT(pkg != NULL, return NULL); @@ -268,8 +263,6 @@ alpm_list_t SYMEXPORT *alpm_pkg_unused_deltas(alpm_pkg_t *pkg) pkg->size * pkg->handle->deltaratio); } -/** @} */ - #define NUM_MATCHES 6 /** Parses the string representation of a alpm_delta_t object. diff --git a/lib/libalpm/log.c b/lib/libalpm/log.c index 271bd00..ff4505b 100644 --- a/lib/libalpm/log.c +++ b/lib/libalpm/log.c @@ -28,9 +28,8 @@ #include "util.h" #include "alpm.h" -/** \addtogroup alpm_log Logging Functions +/** @file * @brief Functions to log using libalpm - * @{ */ /** A printf-like function for logging. @@ -70,8 +69,6 @@ int SYMEXPORT alpm_logaction(alpm_handle_t *handle, const char *prefix, return ret; } -/** @} */ - void _alpm_log(alpm_handle_t *handle, alpm_loglevel_t flag, const char *fmt, ...) { va_list args; diff --git a/lib/libalpm/package.c b/lib/libalpm/package.c index 1294f8e..3317a95 100644 --- a/lib/libalpm/package.c +++ b/lib/libalpm/package.c @@ -35,9 +35,8 @@ #include "handle.h" #include "deps.h" -/** \addtogroup alpm_packages Package Functions +/** @file * @brief Functions to manipulate libalpm packages - * @{ */ /** Free a package. */ @@ -504,8 +503,6 @@ alpm_list_t SYMEXPORT *alpm_pkg_compute_optionalfor(alpm_pkg_t *pkg) } -/** @} */ - alpm_file_t *_alpm_file_copy(alpm_file_t *dest, const alpm_file_t *src) { diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c index a795a1f..2148aad 100644 --- a/lib/libalpm/trans.c +++ b/lib/libalpm/trans.c @@ -40,9 +40,8 @@ #include "sync.h" #include "alpm.h" -/** \addtogroup alpm_trans Transaction Functions +/** @file * @brief Functions to manipulate libalpm transactions - * @{ */ /** Initialize the transaction. */ @@ -226,8 +225,6 @@ int SYMEXPORT alpm_trans_release(alpm_handle_t *handle) return 0; } -/** @} */ - void _alpm_trans_free(alpm_trans_t *trans) { if(trans == NULL) { diff --git a/lib/libalpm/util.c b/lib/libalpm/util.c index 40a5ebd..da7f51f 100644 --- a/lib/libalpm/util.c +++ b/lib/libalpm/util.c @@ -886,7 +886,6 @@ static char *hex_representation(unsigned char *bytes, size_t size) /** Get the md5 sum of file. * @param filename name of the file * @return the checksum on success, NULL on error - * @addtogroup alpm_misc */ char SYMEXPORT *alpm_compute_md5sum(const char *filename) { @@ -905,7 +904,6 @@ char SYMEXPORT *alpm_compute_md5sum(const char *filename) /** Get the sha256 sum of file. * @param filename name of the file * @return the checksum on success, NULL on error - * @addtogroup alpm_misc */ char SYMEXPORT *alpm_compute_sha256sum(const char *filename) { -- 1.8.5.2

There seems to be no content appropriate for this file. Signed-off-by: Jeremy Heiner <ScalaProtractor at gmail.com> --- doc/Makefile.am | 8 ++------ doc/index.txt | 1 - doc/libalpm.3.txt | 39 --------------------------------------- doc/pacman.8.txt | 4 ++-- doc/pacman.conf.5.txt | 4 ++-- doc/vercmp.8.txt | 2 +- 6 files changed, 7 insertions(+), 51 deletions(-) delete mode 100644 doc/libalpm.3.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index e7ebf58..871a0ad 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -13,8 +13,7 @@ ASCIIDOC_MANS = \ pactree.8 \ PKGBUILD.5 \ makepkg.conf.5 \ - pacman.conf.5 \ - libalpm.3 + pacman.conf.5 HTML_MANPAGES = \ pacman.8.html \ @@ -27,8 +26,7 @@ HTML_MANPAGES = \ pactree.8.html \ PKGBUILD.5.html \ makepkg.conf.5.html \ - pacman.conf.5.html \ - libalpm.3.html + pacman.conf.5.html HTML_OTHER = \ index.html \ @@ -55,7 +53,6 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ - libalpm.3.txt \ footer.txt \ index.txt \ submitting-patches.txt \ @@ -157,7 +154,6 @@ pactree.8 pactree.8.html: pactree.8.txt PKGBUILD.5 PKGBUILD.5.html: PKGBUILD.5.txt PKGBUILD-example.txt makepkg.conf.5 makepkg.conf.5.html: makepkg.conf.5.txt pacman.conf.5 pacman.conf.5.html: pacman.conf.5.txt -libalpm.3 libalpm.3.html: libalpm.3.txt # this one is just a symlink repo-remove.8: repo-add.8 $(RM) repo-remove.8 diff --git a/doc/index.txt b/doc/index.txt index 3c4339e..59227ef 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -40,7 +40,6 @@ There are several man pages available for the programs, utilities, and configuration files dealing with pacman. * linkman:PKGBUILD[5] -* linkman:libalpm[3] * linkman:makepkg[8] * linkman:makepkg.conf[5] * linkman:pacman[8] diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt deleted file mode 100644 index e2ea32c..0000000 --- a/doc/libalpm.3.txt +++ /dev/null @@ -1,39 +0,0 @@ -///// -vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: -///// -libalpm(3) -========== - -Name ----- -libalpm - Arch Linux Package Management (ALPM) library - - -Synopsis --------- -For ease of access, the libalpm manual has been split up into several sections. - -*TODO:* Yes, this man page needs a lot of work. Once we get around to doing -good Doxygen documentation, it will improve. We promise. - -*alpm_databases*:: Database Functions -*alpm_interface*:: Interface Functions -*alpm_list*:: List Functions -*alpm_log*:: Logging Functions -*alpm_misc*:: Miscellaneous Functions -*alpm_packages*:: Package Functions -*alpm_sync*:: Sync Functions -*alpm_trans*:: Transaction Functions - - -Configuration -------------- -See linkman:pacman.conf[5] for more details on configuring libalpm using the -'pacman.conf' file. - - -See Also --------- -linkman:pacman[8], linkman:makepkg[8], linkman:pacman.conf[5] - -include::footer.txt[] diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index ccc0a01..1274499 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -20,7 +20,7 @@ system. It features dependency support, package groups, install and uninstall hooks, and the ability to sync your local machine with a remote repository to automatically upgrade packages. Pacman packages are a zipped tar format. -Since version 3.0.0, pacman has been the front-end to linkman:libalpm[3], the +Since version 3.0.0, pacman has been the front-end to libalpm, the ``Arch Linux Package Management'' library. This library allows alternative front-ends to be written (for instance, a GUI front-end). @@ -482,6 +482,6 @@ See linkman:pacman.conf[5] for more details on configuring pacman using the See Also -------- -linkman:pacman.conf[5], linkman:makepkg[8], linkman:libalpm[3] +linkman:pacman.conf[5], linkman:makepkg[8] include::footer.txt[] diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index 9c3dffe..a9dbcb9 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -16,7 +16,7 @@ Synopsis Description ----------- -Pacman, using linkman:libalpm[3], will attempt to read pacman.conf each time it +Pacman will attempt to read pacman.conf each time it is invoked. This configuration file is divided into sections or repositories. Each section defines a package repository that pacman can use when searching for packages in '\--sync' mode. The exception to this is the options section, @@ -352,6 +352,6 @@ linkman:repo-add[8]. See Also -------- -linkman:pacman[8], linkman:libalpm[3] +linkman:pacman[8] include::footer.txt[] diff --git a/doc/vercmp.8.txt b/doc/vercmp.8.txt index 6b94f3e..234146c 100644 --- a/doc/vercmp.8.txt +++ b/doc/vercmp.8.txt @@ -71,6 +71,6 @@ There is none. See Also -------- -linkman:pacman[8], linkman:makepkg[8], linkman:libalpm[3] +linkman:pacman[8], linkman:makepkg[8] include::footer.txt[] -- 1.8.5.2