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
- * @return a archive structure for the package mtree file
+ * @param pkg the local package to read the mtree of
+ * @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 */