[pacman-dev] [PATCH] alpm.h: add/improve function documentation

[Rémy Oudompheng]

Signed-off-by: Rémy Oudompheng <remy at archlinux.org>
---
 lib/libalpm/add.c  |    5 +----
 lib/libalpm/alpm.h |   30 +++++++++++++++++++++++++-----
 lib/libalpm/sync.c |    4 +---
 3 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/lib/libalpm/add.c b/lib/libalpm/add.c
index 0a5cb53..6b2bd7a 100644
--- a/lib/libalpm/add.c
+++ b/lib/libalpm/add.c
@@ -49,10 +49,7 @@
 #include "remove.h"
 #include "handle.h"
 
-/** Add a package to the transaction.
- * @param pkg the package to add
- * @return 0 on success, -1 on error (pm_errno is set accordingly)
- */
+/** Add a package to the transaction. */
 int SYMEXPORT alpm_add_pkg(pmpkg_t *pkg)
 {
 	const char *pkgname, *pkgver;
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 7259957..12c2729 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -258,7 +258,8 @@ const char *alpm_db_get_name(const pmdb_t *db);
  */
 const char *alpm_db_get_url(const pmdb_t *db);
 
-/** Set the serverlist of a database.
+/** Add a new server for a database.
+ * An empty string or NULL can be passed to empty the current server list.
  * @param db database pointer
  * @param url url of the server
  * @return 0 on success, -1 on error (pm_errno is set accordingly)
@@ -293,10 +294,10 @@ pmgrp_t *alpm_db_readgrp(pmdb_t *db, const char *name);
  */
 alpm_list_t *alpm_db_get_grpcache(pmdb_t *db);
 
-/** Searches a database.
+/** Searches a database with regular expressions.
  * @param db pointer to the package database to search in
- * @param needles the list of strings to search for
- * @return the list of packages on success, NULL on error
+ * @param needles a list of regular expressions to search for
+ * @return the list of packages matching all regular expressions on success, NULL on error
  */
 alpm_list_t *alpm_db_search(pmdb_t *db, const alpm_list_t* needles);
 
@@ -318,7 +319,8 @@ int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason);
 /** Create a package from a file.
  * If full is false, the archive is read only until all necessary
  * metadata is found. If it is true, the entire archive is read, which
- * serves as a verfication of integrity and the filelist can be created.
+ * serves as a verification of integrity and the filelist can be created.
+ * The allocated structure should be freed using alpm_pkg_free().
  * @param filename location of the package tarball
  * @param full whether to stop the load after metadata is read or continue
  *             through the full archive
@@ -799,9 +801,27 @@ int alpm_trans_release(void);
 
 /** @name Common Transactions */
 /** @{ */
+
+/** Search for packages to upgrade and add them to the transaction.
+ * @param enable_downgrade allow downgrading of packages if the remote version is lower
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_sync_sysupgrade(int enable_downgrade);
+
+/** Add a package to the transaction.
+ * If the package was loaded by alpm_pkg_load(), it will be freed upon
+ * alpm_trans_release() invocation.
+ * @param pkg the package to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_add_pkg(pmpkg_t *pkg);
+
+/** Add a package removal action to the transaction.
+ * @param pkg the package to uninstall
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_remove_pkg(pmpkg_t *pkg);
+
 /** @} */
 
 /** @addtogroup alpm_api_depends Dependency Functions
diff --git a/lib/libalpm/sync.c b/lib/libalpm/sync.c
index 5428e40..f9158a6 100644
--- a/lib/libalpm/sync.c
+++ b/lib/libalpm/sync.c
@@ -83,9 +83,7 @@ pmpkg_t SYMEXPORT *alpm_sync_newversion(pmpkg_t *pkg, alpm_list_t *dbs_sync)
 	return NULL;
 }
 
-/** Search for packages to upgrade and add them to the transaction.
- * @return 0 on success, -1 on error (pm_errno is set accordingly)
- */
+/** Search for packages to upgrade and add them to the transaction. */
 int SYMEXPORT alpm_sync_sysupgrade(int enable_downgrade)
 {
 	alpm_list_t *i, *j, *k;
-- 
1.7.4.4