Docs docs docs

libalpm: move docs from .c files into alpm.h And fix/expand some
along the way.

Signed-off-by: Allan McRae <allan@archlinux.org>

lib/libalpm/add.c

@@ -47,7 +47,6 @@
 #include "remove.h"
 #include "handle.h"
 
-/** Add a package to the transaction. */
 int SYMEXPORT alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
 {
 	const char *pkgname, *pkgver;

lib/libalpm/alpm.c

@@ -32,19 +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.
- * @param root the root path for all filesystem operations
- * @param dbpath the absolute path to the libalpm database
- * @param err an optional variable to hold any error return codes
- * @return a context handle on success, NULL on error, err will be set if provided
- */
 alpm_handle_t SYMEXPORT *alpm_initialize(const char *root, const char *dbpath,
 		alpm_errno_t *err)
 {
@@ -99,14 +86,6 @@ cleanup:
 	return NULL;
 }
 
-/** Release the library.
- * Disconnects from the database, removes handle and lockfile
- * This should be the last alpm call you make.
- * After this returns, handle should be considered invalid and cannot be reused
- * in any way.
- * @param myhandle the context handle
- * @return 0 on success, -1 on error
- */
 int SYMEXPORT alpm_release(alpm_handle_t *myhandle)
 {
 	int ret = 0;
@@ -135,23 +114,11 @@ 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"
- * */
 const char SYMEXPORT *alpm_version(void)
 {
 	return LIB_VERSION;
 }
 
-/** Get the capabilities of the library.
- * @return a bitmask of the capabilities
- * */
 int SYMEXPORT alpm_capabilities(void)
 {
 	return 0

lib/libalpm/alpm.h

@@ -335,6 +335,11 @@ typedef enum _alpm_hook_when_t {
  * Logging facilities
  */
 
+/** \addtogroup alpm_log Logging Functions
+ * @brief Functions to log using libalpm
+ * @{
+ */
+
 /** Logging Levels */
 typedef enum _alpm_loglevel_t {
 	ALPM_LOG_ERROR    = 1,
@@ -345,9 +350,17 @@ typedef enum _alpm_loglevel_t {
 
 typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list);
 
+/** A printf-like function for logging.
+ * @param handle the context handle
+ * @param prefix caller-specific prefix for the log
+ * @param fmt output format
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_logaction(alpm_handle_t *handle, const char *prefix,
 		const char *fmt, ...) __attribute__((format(printf, 3, 4)));
 
+/** @} */
+
 /**
  * Type of events.
  */
@@ -960,12 +973,71 @@ int alpm_db_get_valid(alpm_db_t *db);
 /** @name Accessors to the list of servers for a database.
  * @{
  */
+
+/** Get the list of servers assigned to this db.
+ * @param db pointer to the database to get the servers from
+ * @return a char* list of servers
+ */
 alpm_list_t *alpm_db_get_servers(const alpm_db_t *db);
+
+/** Sets the list of servers for the database to use.
+ * @param db the database to set the servers
+ * @param a char* list of servers. Note: the database will
+ * take ownership of the list and it should no longer be
+ * freed by the caller
+ */
 int alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers);
+
+/** Add a download server to a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_db_add_server(alpm_db_t *db, const char *url);
+
+/** Remove a download server from a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, 1 on server not present,
+ * -1 on error (pm_errno is set accordingly)
+ */
 int alpm_db_remove_server(alpm_db_t *db, const char *url);
 /** @} */
 
+/** Update a package database
+ *
+ * An update of the package database \a db will be attempted. Unless
+ * \a force is true, the update will only be performed if the remote
+ * database was modified since the last update.
+ *
+ * This operation requires a database lock, and will return an applicable error
+ * if the lock could not be obtained.
+ *
+ * Example:
+ * @code
+ * alpm_list_t *syncs = alpm_get_syncdbs();
+ * for(i = syncs; i; i = alpm_list_next(i)) {
+ *     alpm_db_t *db = alpm_list_getdata(i);
+ *     result = alpm_db_update(0, db);
+ *
+ *     if(result < 0) {
+ *	       printf("Unable to update database: %s\n", alpm_strerrorlast());
+ *     } else if(result == 1) {
+ *         printf("Database already up to date\n");
+ *     } else {
+ *         printf("Database updated\n");
+ *     }
+ * }
+ * @endcode
+ *
+ * @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
+ * the database isn't up to date
+ * @param db pointer to the package database to update
+ * @return 0 on success, -1 on error (pm_errno is set accordingly), 1 if up to
+ * to date
+ */
 int alpm_db_update(int force, alpm_db_t *db);
 
 /** Get a package entry from a package database.
@@ -1069,7 +1141,20 @@ int alpm_pkg_free(alpm_pkg_t *pkg);
  */
 int alpm_pkg_checkmd5sum(alpm_pkg_t *pkg);
 
-/** Compare two version strings and determine which one is 'newer'. */
+/** Compare two version strings and determine which one is 'newer'.
+ * Returns a value comparable to the way strcmp works. Returns 1
+ * if a is newer than b, 0 if a and b are the same version, or -1
+ * if b is newer than a.
+ *
+ * Different epoch values for version strings will override any further
+ * comparison. If no epoch is provided, 0 is assumed.
+ *
+ * Keep in mind that the pkgrel is only compared if it is available
+ * on both versions handed to this function. For example, comparing
+ * 1.5-1 and 1.5 will yield 0; comparing 1.5-1 and 1.5-2 will yield
+ * -1 as expected. This is mainly for supporting versioned dependencies
+ * that do not include the pkgrel.
+ */
 int alpm_pkg_vercmp(const char *a, const char *b);
 
 /** Computes the list of packages requiring a given package.
@@ -1317,11 +1402,15 @@ void *alpm_pkg_changelog_open(alpm_pkg_t *pkg);
 size_t alpm_pkg_changelog_read(void *ptr, size_t size,
 		const alpm_pkg_t *pkg, void *fp);
 
+/** Close a package changelog for reading.
+ * @param pkg the package to close the changelog of (either file or db)
+ * @return 0 on success, -1 on error
+ */
 int alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp);
 
 /** Open a package mtree file for reading.
- * @param pkg the local package to read the changelog of
+ * @param pkg the local package to read the mtree of
- * @return a archive structure for the package mtree file
+ * @return an archive structure for the package mtree file
  */
 struct archive *alpm_pkg_mtree_open(alpm_pkg_t *pkg);
 
@@ -1334,6 +1423,10 @@ struct archive *alpm_pkg_mtree_open(alpm_pkg_t *pkg);
 int alpm_pkg_mtree_next(const alpm_pkg_t *pkg, struct archive *archive,
 		struct archive_entry **entry);
 
+/** Close a package mtree file.
+ * @param pkg the local package to close the mtree of
+ * @param the archive to close
+ */
 int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive);
 
 /** Returns whether the package has an install scriptlet.
@@ -1341,8 +1434,7 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive);
  */
 int alpm_pkg_has_scriptlet(alpm_pkg_t *pkg);
 
-/** Returns the size of download.
+/** Returns the size of the files that will be downloaded to install a
- * Returns the size of the files that will be downloaded to install a
  * package.
  * @param newpkg the new package to upgrade to
  * @return the size of the download
@@ -1380,15 +1472,48 @@ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path)
  * Signatures
  */
 
+/**
+ * Check the PGP signature for the given package file.
+ * @param pkg the package to check
+ * @param siglist a pointer to storage for signature results
+ * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred)
+ */
 int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist);
 
+/**
+ * Check the PGP signature for the given database.
+ * @param db the database to check
+ * @param siglist a pointer to storage for signature results
+ * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred)
+ */
 int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist);
 
+/**
+ * Clean up and free a signature result list.
+ * Note that this does not free the siglist object itself in case that
+ * was allocated on the stack; this is the responsibility of the caller.
+ * @param siglist a pointer to storage for signature results
+ * @return 0 on success, -1 on error
+ */
 int alpm_siglist_cleanup(alpm_siglist_t *siglist);
 
+/**
+ * Decode a loaded signature in base64 form.
+ * @param base64_data the signature to attempt to decode
+ * @param data the decoded data; must be freed by the caller
+ * @param data_len the length of the returned data
+ * @return 0 on success, -1 on failure to properly decode
+ */
 int alpm_decode_signature(const char *base64_data,
 		unsigned char **data, size_t *data_len);
 
+/**
+ * Extract the Issuer Key ID from a signature
+ * @param sig PGP signature
+ * @param len length of signature
+ * @param keys a pointer to storage for key IDs
+ * @return 0 on success, -1 on error
+ */
 int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
 		const unsigned char *sig, const size_t len, alpm_list_t **keys);
 
@@ -1396,12 +1521,22 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
  * Groups
  */
 
+/** Find group members across a list of databases.
+ * If a member exists in several databases, only the first database is used.
+ * IgnorePkg is also handled.
+ * @param dbs the list of alpm_db_t *
+ * @param name the name of the group
+ * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free)
+ */
 alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name);
 
 /*
  * Sync
  */
 
+/** Check for new version of pkg in sync repos
+ * (only the first occurrence is considered in sync)
+ */
 alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync);
 
 /** @addtogroup alpm_api_trans Transaction Functions
@@ -1534,12 +1669,49 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg);
  * @{
  */
 
+/** Checks dependencies and returns missing ones in a list.
+ * Dependencies can include versions with depmod operators.
+ * @param handle the context handle
+ * @param pkglist the list of local packages
+ * @param remove an alpm_list_t* of packages to be removed
+ * @param upgrade an alpm_list_t* of packages to be upgraded (remove-then-upgrade)
+ * @param reversedeps handles the backward dependencies
+ * @return an alpm_list_t* of alpm_depmissing_t pointers.
+ */
 alpm_list_t *alpm_checkdeps(alpm_handle_t *handle, alpm_list_t *pkglist,
 		alpm_list_t *remove, alpm_list_t *upgrade, int reversedeps);
+
+/** Find a package satisfying a specified dependency.
+ * The dependency can include versions with depmod operators.
+ * @param pkgs an alpm_list_t* of alpm_pkg_t where the satisfier will be searched
+ * @param depstring package or provision name, versioned or not
+ * @return a alpm_pkg_t* satisfying depstring
+ */
 alpm_pkg_t *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring);
+
+/** Find a package satisfying a specified dependency.
+ * First look for a literal, going through each db one by one. Then look for
+ * providers. The first satisfier that belongs to an installed package is
+ * returned. If no providers belong to an installed package then an
+ * alpm_question_select_provider_t is created to select the provider.
+ * The dependency can include versions with depmod operators.
+ *
+ * @param handle the context handle
+ * @param dbs an alpm_list_t* of alpm_db_t where the satisfier will be searched
+ * @param depstring package or provision name, versioned or not
+ * @return a alpm_pkg_t* satisfying depstring
+ */
 alpm_pkg_t *alpm_find_dbs_satisfier(alpm_handle_t *handle,
 		alpm_list_t *dbs, const char *depstring);
 
+/**
+ * @brief Check the package conflicts in a database
+ *
+ * @param handle the context handle
+ * @param pkglist the list of packages to check
+ *
+ * @return an alpm_list_t of alpm_conflict_t
+ */
 alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist);
 
 /** Returns a newly allocated string representing the dependency information.
@@ -1568,12 +1740,60 @@ void alpm_dep_free(alpm_depend_t *dep);
  */
 
 /* checksums */
+
+/** \addtogroup alpm_misc Miscellaneous Functions
+ * @brief Various libalpm functions
+ * @{
+ */
+
+/** Get the md5 sum of file.
+ * @param filename name of the file
+ * @return the checksum on success, NULL on error
+ */
 char *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
+ */
 char *alpm_compute_sha256sum(const char *filename);
 
+/** @} */
+
+/** \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.
+ * @param root the root path for all filesystem operations
+ * @param dbpath the absolute path to the libalpm database
+ * @param err an optional variable to hold any error return codes
+ * @return a context handle on success, NULL on error, err will be set if provided
+ */
 alpm_handle_t *alpm_initialize(const char *root, const char *dbpath,
 		alpm_errno_t *err);
+
+/** Release the library.
+ * Disconnects from the database, removes handle and lockfile
+ * This should be the last alpm call you make.
+ * After this returns, handle should be considered invalid and cannot be reused
+ * in any way.
+ * @param myhandle the context handle
+ * @return 0 on success, -1 on error
+ */
 int alpm_release(alpm_handle_t *handle);
+
+/** @} */
+
+/** Remove the database lock file
+ * @param handle the context handle
+ * @return 0 on success, -1 on error
+ *
+ * @note Safe to call from inside signal handlers.
+ */
 int alpm_unlock(alpm_handle_t *handle);
 
 enum alpm_caps {
@@ -1582,12 +1802,27 @@ enum alpm_caps {
 	ALPM_CAPABILITY_SIGNATURES = (1 << 2)
 };
 
+/** Get the version of library.
+ * @return the library version, e.g. "6.0.4"
+ * */
 const char *alpm_version(void);
-/* Return a bitfield of capabilities using values from 'enum alpm_caps' */
+
+/** Get the capabilities of the library.
+ * @return a bitmask of the capabilities
+ * */
 int alpm_capabilities(void);
 
+/**
+ * Free a fileconflict and its members.
+ * @param conflict the fileconflict to free
+ */
 void alpm_fileconflict_free(alpm_fileconflict_t *conflict);
 void alpm_depmissing_free(alpm_depmissing_t *miss);
+
+/**
+ * Free a conflict and its members.
+ * @param conflict the conflict to free
+ */
 void alpm_conflict_free(alpm_conflict_t *conflict);
 
 /* End of alpm_api */

lib/libalpm/be_sync.c

@@ -136,41 +136,6 @@ valid:
 	return 0;
 }
 
-/** Update a package database
- *
- * An update of the package database \a db will be attempted. Unless
- * \a force is true, the update will only be performed if the remote
- * database was modified since the last update.
- *
- * This operation requires a database lock, and will return an applicable error
- * if the lock could not be obtained.
- *
- * Example:
- * @code
- * alpm_list_t *syncs = alpm_get_syncdbs();
- * for(i = syncs; i; i = alpm_list_next(i)) {
- *     alpm_db_t *db = alpm_list_getdata(i);
- *     result = alpm_db_update(0, db);
- *
- *     if(result < 0) {
- *	       printf("Unable to update database: %s\n", alpm_strerrorlast());
- *     } else if(result == 1) {
- *         printf("Database already up to date\n");
- *     } else {
- *         printf("Database updated\n");
- *     }
- * }
- * @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
- * the database isn't up to date
- * @param db pointer to the package database to update
- * @return 0 on success, -1 on error (pm_errno is set accordingly), 1 if up to
- * to date
- */
 int SYMEXPORT alpm_db_update(int force, alpm_db_t *db)
 {
 	char *syncpath;

lib/libalpm/conflict.c

@@ -63,9 +63,6 @@ error:
 	return NULL;
 }
 
-/**
- * @brief Free a conflict and its members.
- */
 void SYMEXPORT alpm_conflict_free(alpm_conflict_t *conflict)
 {
 	ASSERT(conflict != NULL, return);
@@ -243,14 +240,6 @@ alpm_list_t *_alpm_outerconflicts(alpm_db_t *db, alpm_list_t *packages)
 	return baddeps;
 }
 
-/**
- * @brief Check the package conflicts in a database
- *
- * @param handle the context handle
- * @param pkglist the list of packages to check
- *
- * @return an alpm_list_t of alpm_conflict_t
- */
 alpm_list_t SYMEXPORT *alpm_checkconflicts(alpm_handle_t *handle,
 		alpm_list_t *pkglist)
 {
@@ -300,9 +289,6 @@ error:
 	RET_ERR(handle, ALPM_ERR_MEMORY, conflicts);
 }
 
-/**
- * @brief Frees a conflict and its members.
- */
 void SYMEXPORT alpm_fileconflict_free(alpm_fileconflict_t *conflict)
 {
 	ASSERT(conflict != NULL, return);

lib/libalpm/db.c

@@ -37,12 +37,6 @@
 #include "package.h"
 #include "group.h"
 
-/** \addtogroup alpm_databases Database Functions
- * @brief Functions to query and manipulate the database of libalpm
- * @{
- */
-
-/** Register a sync database of packages. */
 alpm_db_t SYMEXPORT *alpm_register_syncdb(alpm_handle_t *handle,
 		const char *treename, int siglevel)
 {
@@ -81,7 +75,6 @@ void _alpm_db_unregister(alpm_db_t *db)
 	_alpm_db_free(db);
 }
 
-/** Unregister all package databases. */
 int SYMEXPORT alpm_unregister_all_syncdbs(alpm_handle_t *handle)
 {
 	alpm_list_t *i;
@@ -102,7 +95,6 @@ int SYMEXPORT alpm_unregister_all_syncdbs(alpm_handle_t *handle)
 	return 0;
 }
 
-/** Unregister a package database. */
 int SYMEXPORT alpm_db_unregister(alpm_db_t *db)
 {
 	int found = 0;
@@ -139,14 +131,12 @@ int SYMEXPORT alpm_db_unregister(alpm_db_t *db)
 	return 0;
 }
 
-/** Get the serverlist of a database. */
 alpm_list_t SYMEXPORT *alpm_db_get_servers(const alpm_db_t *db)
 {
 	ASSERT(db != NULL, return NULL);
 	return db->servers;
 }
 
-/** Set the serverlist of a database. */
 int SYMEXPORT alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers)
 {
 	ASSERT(db != NULL, return -1);
@@ -168,11 +158,6 @@ static char *sanitize_url(const char *url)
 	return newurl;
 }
 
-/** Add a download server to a database.
- * @param db database pointer
- * @param url url of the server
- * @return 0 on success, -1 on error (pm_errno is set accordingly)
- */
 int SYMEXPORT alpm_db_add_server(alpm_db_t *db, const char *url)
 {
 	char *newurl;
@@ -193,12 +178,6 @@ int SYMEXPORT alpm_db_add_server(alpm_db_t *db, const char *url)
 	return 0;
 }
 
-/** Remove a download server from a database.
- * @param db database pointer
- * @param url url of the server
- * @return 0 on success, 1 on server not present,
- * -1 on error (pm_errno is set accordingly)
- */
 int SYMEXPORT alpm_db_remove_server(alpm_db_t *db, const char *url)
 {
 	char *newurl, *vdata = NULL;
@@ -227,14 +206,12 @@ int SYMEXPORT alpm_db_remove_server(alpm_db_t *db, const char *url)
 	return ret;
 }
 
-/** Get the name of a package database. */
 const char SYMEXPORT *alpm_db_get_name(const alpm_db_t *db)
 {
 	ASSERT(db != NULL, return NULL);
 	return db->treename;
 }
 
-/** Get the signature verification level for a database. */
 int SYMEXPORT alpm_db_get_siglevel(alpm_db_t *db)
 {
 	ASSERT(db != NULL, return -1);
@@ -245,7 +222,6 @@ int SYMEXPORT alpm_db_get_siglevel(alpm_db_t *db)
 	}
 }
 
-/** Check the validity of a database. */
 int SYMEXPORT alpm_db_get_valid(alpm_db_t *db)
 {
 	ASSERT(db != NULL, return -1);
@@ -253,7 +229,6 @@ int SYMEXPORT alpm_db_get_valid(alpm_db_t *db)
 	return db->ops->validate(db);
 }
 
-/** Get a package entry from a package database. */
 alpm_pkg_t SYMEXPORT *alpm_db_get_pkg(alpm_db_t *db, const char *name)
 {
 	alpm_pkg_t *pkg;
@@ -269,7 +244,6 @@ alpm_pkg_t SYMEXPORT *alpm_db_get_pkg(alpm_db_t *db, const char *name)
 	return pkg;
 }
 
-/** Get the package cache of a package database. */
 alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(alpm_db_t *db)
 {
 	ASSERT(db != NULL, return NULL);
@@ -277,7 +251,6 @@ alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(alpm_db_t *db)
 	return _alpm_db_get_pkgcache(db);
 }
 
-/** Get a group entry from a package database. */
 alpm_group_t SYMEXPORT *alpm_db_get_group(alpm_db_t *db, const char *name)
 {
 	ASSERT(db != NULL, return NULL);
@@ -288,7 +261,6 @@ alpm_group_t SYMEXPORT *alpm_db_get_group(alpm_db_t *db, const char *name)
 	return _alpm_db_get_groupfromcache(db, name);
 }
 
-/** Get the group cache of a package database. */
 alpm_list_t SYMEXPORT *alpm_db_get_groupcache(alpm_db_t *db)
 {
 	ASSERT(db != NULL, return NULL);
@@ -297,7 +269,6 @@ alpm_list_t SYMEXPORT *alpm_db_get_groupcache(alpm_db_t *db)
 	return _alpm_db_get_groupcache(db);
 }
 
-/** Searches a database. */
 int SYMEXPORT alpm_db_search(alpm_db_t *db, const alpm_list_t *needles,
 		alpm_list_t **ret)
 {
@@ -308,7 +279,6 @@ int SYMEXPORT alpm_db_search(alpm_db_t *db, const alpm_list_t *needles,
 	return _alpm_db_search(db, needles, ret);
 }
 
-/** Sets the usage bitmask for a repo */
 int SYMEXPORT alpm_db_set_usage(alpm_db_t *db, int usage)
 {
 	ASSERT(db != NULL, return -1);
@@ -316,7 +286,6 @@ int SYMEXPORT alpm_db_set_usage(alpm_db_t *db, int usage)
 	return 0;
 }
 
-/** Gets the usage bitmask for a repo */
 int SYMEXPORT alpm_db_get_usage(alpm_db_t *db, int *usage)
 {
 	ASSERT(db != NULL, return -1);
@@ -325,9 +294,6 @@ int SYMEXPORT alpm_db_get_usage(alpm_db_t *db, int *usage)
 	return 0;
 }
 
-
-/** @} */
-
 alpm_db_t *_alpm_db_new(const char *treename, int is_local)
 {
 	alpm_db_t *db;

lib/libalpm/deps.c

@@ -286,12 +286,6 @@ static int no_dep_version(alpm_handle_t *handle)
 	return (handle->trans->flags & ALPM_TRANS_FLAG_NODEPVERSION);
 }
 
-/** Find a package satisfying a specified dependency.
- * The dependency can include versions with depmod operators.
- * @param pkgs an alpm_list_t* of alpm_pkg_t where the satisfier will be searched
- * @param depstring package or provision name, versioned or not
- * @return a alpm_pkg_t* satisfying depstring
- */
 alpm_pkg_t SYMEXPORT *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring)
 {
 	alpm_depend_t *dep = alpm_dep_from_string(depstring);
@@ -303,15 +297,6 @@ alpm_pkg_t SYMEXPORT *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstri
 	return pkg;
 }
 
-/** Checks dependencies and returns missing ones in a list.
- * Dependencies can include versions with depmod operators.
- * @param handle the context handle
- * @param pkglist the list of local packages
- * @param remove an alpm_list_t* of packages to be removed
- * @param upgrade an alpm_list_t* of packages to be upgraded (remove-then-upgrade)
- * @param reversedeps handles the backward dependencies
- * @return an alpm_list_t* of alpm_depmissing_t pointers.
- */
 alpm_list_t SYMEXPORT *alpm_checkdeps(alpm_handle_t *handle,
 		alpm_list_t *pkglist, alpm_list_t *rem, alpm_list_t *upgrade,
 		int reversedeps)
@@ -763,18 +748,6 @@ static alpm_pkg_t *resolvedep(alpm_handle_t *handle, alpm_depend_t *dep,
 	return NULL;
 }
 
-/** Find a package satisfying a specified dependency.
- * First look for a literal, going through each db one by one. Then look for
- * providers. The first satisfier that belongs to an installed package is
- * returned. If no providers belong to an installed package then an
- * alpm_question_select_provider_t is created to select the provider.
- * The dependency can include versions with depmod operators.
- *
- * @param handle the context handle
- * @param dbs an alpm_list_t* of alpm_db_t where the satisfier will be searched
- * @param depstring package or provision name, versioned or not
- * @return a alpm_pkg_t* satisfying depstring
- */
 alpm_pkg_t SYMEXPORT *alpm_find_dbs_satisfier(alpm_handle_t *handle,
 		alpm_list_t *dbs, const char *depstring)
 {
@@ -889,11 +862,6 @@ int _alpm_resolvedeps(alpm_handle_t *handle, alpm_list_t *localpkgs,
 	return ret;
 }
 
-/** Reverse of splitdep; make a dep string from a alpm_depend_t struct.
- * The string must be freed!
- * @param dep the depend to turn into a string
- * @return a string-formatted dependency with operator if necessary
- */
 char SYMEXPORT *alpm_dep_compute_string(const alpm_depend_t *dep)
 {
 	const char *name, *opr, *ver, *desc_delim, *desc;

lib/libalpm/dload.c

@@ -652,7 +652,6 @@ static char *filecache_find_url(alpm_handle_t *handle, const char *url)
 	return _alpm_filecache_find(handle, filebase);
 }
 
-/** Fetch a remote pkg. */
 char SYMEXPORT *alpm_fetch_pkgurl(alpm_handle_t *handle, const char *url)
 {
 	char *filepath;

lib/libalpm/handle.c

@@ -123,12 +123,6 @@ int _alpm_handle_lock(alpm_handle_t *handle)
 	return (handle->lockfd >= 0 ? 0 : -1);
 }
 
-/** Remove the database lock file
- * @param handle the context handle
- * @return 0 on success, -1 on error
- *
- * @note Safe to call from inside signal handlers.
- */
 int SYMEXPORT alpm_unlock(alpm_handle_t *handle)
 {
 	ASSERT(handle != NULL, return -1);

lib/libalpm/log.c

@@ -30,11 +30,6 @@
 #include "util.h"
 #include "alpm.h"
 
-/** \addtogroup alpm_log Logging Functions
- * @brief Functions to log using libalpm
- * @{
- */
-
 static int _alpm_log_leader(FILE *f, const char *prefix)
 {
 	time_t t = time(NULL);
@@ -47,12 +42,6 @@ static int _alpm_log_leader(FILE *f, const char *prefix)
 	return fprintf(f, "[%s] [%s] ", timestamp, prefix);
 }
 
-/** A printf-like function for logging.
- * @param handle the context handle
- * @param prefix caller-specific prefix for the log
- * @param fmt output format
- * @return 0 on success, -1 on error (pm_errno is set accordingly)
- */
 int SYMEXPORT alpm_logaction(alpm_handle_t *handle, const char *prefix,
 		const char *fmt, ...)
 {
@@ -109,8 +98,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;

lib/libalpm/package.c

@@ -34,12 +34,6 @@
 #include "handle.h"
 #include "deps.h"
 
-/** \addtogroup alpm_packages Package Functions
- * @brief Functions to manipulate libalpm packages
- * @{
- */
-
-/** Free a package. */
 int SYMEXPORT alpm_pkg_free(alpm_pkg_t *pkg)
 {
 	ASSERT(pkg != NULL, return -1);
@@ -52,7 +46,6 @@ int SYMEXPORT alpm_pkg_free(alpm_pkg_t *pkg)
 	return 0;
 }
 
-/** Check the integrity (with md5) of a package from the sync cache. */
 int SYMEXPORT alpm_pkg_checkmd5sum(alpm_pkg_t *pkg)
 {
 	char *fpath;
@@ -397,7 +390,6 @@ alpm_db_t SYMEXPORT *alpm_pkg_get_db(alpm_pkg_t *pkg)
 	return pkg->origin_data.db;
 }
 
-/** Open a package changelog for reading. */
 void SYMEXPORT *alpm_pkg_changelog_open(alpm_pkg_t *pkg)
 {
 	ASSERT(pkg != NULL, return NULL);
@@ -405,7 +397,6 @@ void SYMEXPORT *alpm_pkg_changelog_open(alpm_pkg_t *pkg)
 	return pkg->ops->changelog_open(pkg);
 }
 
-/** Read data from an open changelog 'file stream'. */
 size_t SYMEXPORT alpm_pkg_changelog_read(void *ptr, size_t size,
 		const alpm_pkg_t *pkg, void *fp)
 {
@@ -414,7 +405,6 @@ size_t SYMEXPORT alpm_pkg_changelog_read(void *ptr, size_t size,
 	return pkg->ops->changelog_read(ptr, size, pkg, fp);
 }
 
-/** Close a package changelog for reading. */
 int SYMEXPORT alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp)
 {
 	ASSERT(pkg != NULL, return -1);
@@ -422,7 +412,6 @@ int SYMEXPORT alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp)
 	return pkg->ops->changelog_close(pkg, fp);
 }
 
-/** Open a package mtree file for reading. */
 struct archive SYMEXPORT *alpm_pkg_mtree_open(alpm_pkg_t * pkg)
 {
 	ASSERT(pkg != NULL, return NULL);
@@ -430,7 +419,6 @@ struct archive SYMEXPORT *alpm_pkg_mtree_open(alpm_pkg_t * pkg)
 	return pkg->ops->mtree_open(pkg);
 }
 
-/** Read entry from an open mtree file. */
 int SYMEXPORT alpm_pkg_mtree_next(const alpm_pkg_t * pkg, struct archive *archive,
 	struct archive_entry **entry)
 {
@@ -439,7 +427,6 @@ int SYMEXPORT alpm_pkg_mtree_next(const alpm_pkg_t * pkg, struct archive *archiv
 	return pkg->ops->mtree_next(pkg, archive, entry);
 }
 
-/** Close a package mtree file for reading. */
 int SYMEXPORT alpm_pkg_mtree_close(const alpm_pkg_t * pkg, struct archive *archive)
 {
 	ASSERT(pkg != NULL, return -1);
@@ -510,21 +497,16 @@ static alpm_list_t *compute_requiredby(alpm_pkg_t *pkg, int optional)
 	return reqs;
 }
 
-/** Compute the packages requiring a given package. */
 alpm_list_t SYMEXPORT *alpm_pkg_compute_requiredby(alpm_pkg_t *pkg)
 {
 	return compute_requiredby(pkg, 0);
 }
 
-/** Compute the packages optionally requiring a given package. */
 alpm_list_t SYMEXPORT *alpm_pkg_compute_optionalfor(alpm_pkg_t *pkg)
 {
 	return compute_requiredby(pkg, 1);
 }
 
-
-/** @} */
-
 alpm_file_t *_alpm_file_copy(alpm_file_t *dest,
 		const alpm_file_t *src)
 {
@@ -764,16 +746,6 @@ alpm_pkg_t SYMEXPORT *alpm_pkg_find(alpm_list_t *haystack, const char *needle)
 	return NULL;
 }
 
-/** Test if a package should be ignored.
- *
- * Checks if the package is ignored via IgnorePkg, or if the package is
- * in a group ignored via IgnoreGroup.
- *
- * @param handle the context handle
- * @param pkg the package to test
- *
- * @return 1 if the package should be ignored, 0 otherwise
- */
 int SYMEXPORT alpm_pkg_should_ignore(alpm_handle_t *handle, alpm_pkg_t *pkg)
 {
 	alpm_list_t *groups = NULL;

lib/libalpm/remove.c

@@ -46,14 +46,6 @@
 #include "handle.h"
 #include "filelist.h"
 
-/**
- * @brief Add a package removal action to the transaction.
- *
- * @param handle the context handle
- * @param pkg the package to uninstall
- *
- * @return 0 on success, -1 on error
- */
 int SYMEXPORT alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
 {
 	const char *pkgname;

lib/libalpm/signing.c

@@ -35,14 +35,6 @@
 #include "alpm.h"
 #include "handle.h"
 
-/**
- * Decode a loaded signature in base64 form.
- * @param base64_data the signature to attempt to decode
- * @param data the decoded data; must be freed by the caller
- * @param data_len the length of the returned data
- * @return 0 on success, -1 on failure to properly decode
- */
-
 int SYMEXPORT alpm_decode_signature(const char *base64_data,
 		unsigned char **data, size_t *data_len)
 {
@@ -999,12 +991,6 @@ int _alpm_process_siglist(alpm_handle_t *handle, const char *identifier,
 	return retry;
 }
 
-/**
- * Check the PGP signature for the given package file.
- * @param pkg the package to check
- * @param siglist a pointer to storage for signature results
- * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred)
- */
 int SYMEXPORT alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg,
 		alpm_siglist_t *siglist)
 {
@@ -1016,12 +1002,6 @@ int SYMEXPORT alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg,
 			pkg->base64_sig, siglist);
 }
 
-/**
- * Check the PGP signature for the given database.
- * @param db the database to check
- * @param siglist a pointer to storage for signature results
- * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred)
- */
 int SYMEXPORT alpm_db_check_pgp_signature(alpm_db_t *db,
 		alpm_siglist_t *siglist)
 {
@@ -1032,13 +1012,6 @@ int SYMEXPORT alpm_db_check_pgp_signature(alpm_db_t *db,
 	return _alpm_gpgme_checksig(db->handle, _alpm_db_path(db), NULL, siglist);
 }
 
-/**
- * Clean up and free a signature result list.
- * Note that this does not free the siglist object itself in case that
- * was allocated on the stack; this is the responsibility of the caller.
- * @param siglist a pointer to storage for signature results
- * @return 0 on success, -1 on error
- */
 int SYMEXPORT alpm_siglist_cleanup(alpm_siglist_t *siglist)
 {
 	ASSERT(siglist != NULL, return -1);
@@ -1119,13 +1092,6 @@ static int parse_subpacket(alpm_handle_t *handle, const char *identifier,
 		return 0;
 }
 
-/**
- * Extract the Issuer Key ID from a signature
- * @param sig PGP signature
- * @param len length of signature
- * @param keys a pointer to storage for key IDs
- * @return 0 on success, -1 on error
- */
 int SYMEXPORT alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
 		const unsigned char *sig, const size_t len, alpm_list_t **keys)
 {

lib/libalpm/sync.c

@@ -52,10 +52,6 @@ struct keyinfo_t {
        char* keyid;
 };
 
-
-/** Check for new version of pkg in sync repos
- * (only the first occurrence is considered in sync)
- */
 alpm_pkg_t SYMEXPORT *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync)
 {
 	alpm_list_t *i;
@@ -200,7 +196,6 @@ static alpm_list_t *check_replacers(alpm_handle_t *handle, alpm_pkg_t *lpkg,
 	return replacers;
 }
 
-/** Search for packages to upgrade and add them to the transaction. */
 int SYMEXPORT alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade)
 {
 	alpm_list_t *i, *j;
@@ -256,13 +251,6 @@ int SYMEXPORT alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade)
 	return 0;
 }
 
-/** Find group members across a list of databases.
- * If a member exists in several databases, only the first database is used.
- * IgnorePkg is also handled.
- * @param dbs the list of alpm_db_t *
- * @param name the name of the group
- * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free)
- */
 alpm_list_t SYMEXPORT *alpm_find_group_pkgs(alpm_list_t *dbs,
 		const char *name)
 {
@@ -673,11 +661,6 @@ cleanup:
 	return ret;
 }
 
-/** Returns the size of the files that will be downloaded to install a
- * package.
- * @param newpkg the new package to upgrade to
- * @return the size of the download
- */
 off_t SYMEXPORT alpm_pkg_download_size(alpm_pkg_t *newpkg)
 {
 	if(!(newpkg->infolevel & INFRQ_DSIZE)) {

lib/libalpm/trans.c

@@ -42,12 +42,6 @@
 #include "deps.h"
 #include "hook.h"
 
-/** \addtogroup alpm_trans Transaction Functions
- * @brief Functions to manipulate libalpm transactions
- * @{
- */
-
-/** Initialize the transaction. */
 int SYMEXPORT alpm_trans_init(alpm_handle_t *handle, int flags)
 {
 	alpm_trans_t *trans;
@@ -97,7 +91,6 @@ static alpm_list_t *check_arch(alpm_handle_t *handle, alpm_list_t *pkgs)
 	return invalid;
 }
 
-/** Prepare a transaction. */
 int SYMEXPORT alpm_trans_prepare(alpm_handle_t *handle, alpm_list_t **data)
 {
 	alpm_trans_t *trans;
@@ -156,7 +149,6 @@ int SYMEXPORT alpm_trans_prepare(alpm_handle_t *handle, alpm_list_t **data)
 	return 0;
 }
 
-/** Commit a transaction. */
 int SYMEXPORT alpm_trans_commit(alpm_handle_t *handle, alpm_list_t **data)
 {
 	alpm_trans_t *trans;
@@ -233,9 +225,6 @@ int SYMEXPORT alpm_trans_commit(alpm_handle_t *handle, alpm_list_t **data)
 	return 0;
 }
 
-/** Interrupt a transaction.
- * @note Safe to call from inside signal handlers.
- */
 int SYMEXPORT alpm_trans_interrupt(alpm_handle_t *handle)
 {
 	alpm_trans_t *trans;
@@ -253,7 +242,6 @@ int SYMEXPORT alpm_trans_interrupt(alpm_handle_t *handle)
 	return 0;
 }
 
-/** Release a transaction. */
 int SYMEXPORT alpm_trans_release(alpm_handle_t *handle)
 {
 	alpm_trans_t *trans;

lib/libalpm/util.c

@@ -1023,11 +1023,6 @@ static char *hex_representation(unsigned char *bytes, size_t size)
 	return str;
 }
 
-/** 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)
 {
 	unsigned char output[16];
@@ -1041,11 +1036,6 @@ char SYMEXPORT *alpm_compute_md5sum(const char *filename)
 	return hex_representation(output, 16);
 }
 
-/** 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)
 {
 	unsigned char output[32];

lib/libalpm/version.c

@@ -216,20 +216,6 @@ cleanup:
 	return ret;
 }
 
-/** Compare two version strings and determine which one is 'newer'.
- * Returns a value comparable to the way strcmp works. Returns 1
- * if a is newer than b, 0 if a and b are the same version, or -1
- * if b is newer than a.
- *
- * Different epoch values for version strings will override any further
- * comparison. If no epoch is provided, 0 is assumed.
- *
- * Keep in mind that the pkgrel is only compared if it is available
- * on both versions handed to this function. For example, comparing
- * 1.5-1 and 1.5 will yield 0; comparing 1.5-1 and 1.5-2 will yield
- * -1 as expected. This is mainly for supporting versioned dependencies
- * that do not include the pkgrel.
- */
 int SYMEXPORT alpm_pkg_vercmp(const char *a, const char *b)
 {
 	char *full1, *full2;