[pacman-dev] [PATCH] Fix broken documentation for alpm_trans_prepare()

[Rémy Oudompheng]

The current state of the code does not allow to see immediately
that it returns a list of pmdepmissing_t structures.

Signed-off-by: Rémy Oudompheng <remy at archlinux.org>
---
alpm_trans_prepare() is really unusable if the type
of its return value is obfuscated like this.

This patch applies on branch "maint".

 lib/libalpm/deps.c   |    2 +-
 lib/libalpm/remove.c |    8 ++++++++
 lib/libalpm/trans.c  |    4 ++--
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/lib/libalpm/deps.c b/lib/libalpm/deps.c
index dc85b31..36d6e1a 100644
--- a/lib/libalpm/deps.c
+++ b/lib/libalpm/deps.c
@@ -261,7 +261,7 @@ pmpkg_t SYMEXPORT *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring)
  * @param reversedeps handles the backward dependencies
  * @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)
- * @return an alpm_list_t* of pmpkg_t* of pmdepmissing_t pointers.
+ * @return an alpm_list_t* of pmdepmissing_t pointers.
  */
 alpm_list_t SYMEXPORT *alpm_checkdeps(alpm_list_t *pkglist, int reversedeps,
 		alpm_list_t *remove, alpm_list_t *upgrade)
diff --git a/lib/libalpm/remove.c b/lib/libalpm/remove.c
index 5def92a..7c8a99f 100644
--- a/lib/libalpm/remove.c
+++ b/lib/libalpm/remove.c
@@ -129,6 +129,14 @@ static void remove_prepare_keep_needed(pmtrans_t *trans, pmdb_t *db,
 	}
 }
 
+/** Transaction preparation for remove actions.
+ * This function takes a pointer to a alpm_list_t which will be
+ * filled with a list of pmdepmissing_t* objects representing
+ * the packages blocking the transaction.
+ * @param trans the transaction object
+ * @param db the database of local packages
+ * @param data a pointer to an alpm_list_t* to fill
+ */
 int _alpm_remove_prepare(pmtrans_t *trans, pmdb_t *db, alpm_list_t **data)
 {
 	alpm_list_t *lp;
diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c
index 08856d0..309a56a 100644
--- a/lib/libalpm/trans.c
+++ b/lib/libalpm/trans.c
@@ -177,8 +177,8 @@ static alpm_list_t *check_arch(alpm_list_t *pkgs)
 }
 
 /** Prepare a transaction.
- * @param data the address of an alpm_list where detailed description
- * of an error can be dumped (ie. list of conflicting files)
+ * @param data the address of an alpm_list where a list
+ * of pmdepmissing_t objects is dumped (conflicting packages)
  * @return 0 on success, -1 on error (pm_errno is set accordingly)
  */
 int SYMEXPORT alpm_trans_prepare(alpm_list_t **data)
-- 
1.7.4.4