[pacman-dev] [PATCH] Add documentation for transaction events

[Sebastian Nowicki]

It is hard to decipher what the transaction events actually notify you  
of, and
what parameters are passed to the callback function, without looking  
at the
code. This patch adds documentation for the _pmtransevt_t enum in  
order to
clarify what the event is for and what data is passed when the  
callback is
called.

Signed-off-by: Sebastian Nowicki <sebnow at gmail.com>
---
  lib/libalpm/alpm.h |  166 +++++++++++++++++++++++++++++++++++++++++++ 
++++++++-
  1 files changed, 165 insertions(+), 1 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index a7ea063..0c2da10 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -283,36 +283,200 @@ typedef enum _pmtransflag_t {
  	PM_TRANS_FLAG_RECURSEALL = 0x10000
  } pmtransflag_t;

-/* Transaction Events */
+/**
+ * @addtogroup alpm_trans
+ * @brief Transaction events
+ */
+/*@{*/
  typedef enum _pmtransevt_t {
+	/**
+	 * @brief Dependencies will be computed for a package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_CHECKDEPS_START = 1,
+
+	/**
+	 * @brief Dependencies were computed for a package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_CHECKDEPS_DONE,
+
+	/**
+	 * @brief File conflicts will be computed for a package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_FILECONFLICTS_START,
+
+	/**
+	 * @brief File conflicts were computed for a package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_FILECONFLICTS_DONE,
+
+	/**
+	 * @brief Dependencies will be resolved for target package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_RESOLVEDEPS_START,
+
+	/**
+	 * @brief Dependencies were resolved for target package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_RESOLVEDEPS_DONE,
+
+	/**
+	 * @brief Inter-conflicts will be checked for target package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_INTERCONFLICTS_START,
+
+	/**
+	 * @brief Inter-conflicts were checked for target package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_INTERCONFLICTS_DONE,
+
+	/**
+	 * @brief Package will be installed
+	 *
+	 * A pointer to the target package is passed to the callback
+	 */
  	PM_TRANS_EVT_ADD_START,
+
+	/**
+	 * @brief Package was installed
+	 *
+	 * A pointer to the new package is passed to the callback
+	 */
  	PM_TRANS_EVT_ADD_DONE,
+
+	/**
+	 * @brief Package will be removed
+	 *
+	 * A pointer to the target package is passed to the callback
+	 */
  	PM_TRANS_EVT_REMOVE_START,
+
+	/**
+	 * @brief Package was removed
+	 *
+	 * A pointer to the removed package is passed to the callback
+	 */
  	PM_TRANS_EVT_REMOVE_DONE,
+
+	/**
+	 * @brief Package will be upgraded
+	 *
+	 * A pointer to the upgraded package is passed to the callback
+	 */
  	PM_TRANS_EVT_UPGRADE_START,
+
+	/**
+	 * @brief Package was upgraded
+	 *
+	 * A pointer to the new package, and a pointer to the old package is
+	 * passed to the callback, respectively
+	 */
  	PM_TRANS_EVT_UPGRADE_DONE,
+
+	/**
+	 * @brief Package waas extracted
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_EXTRACT_DONE,
+
+	/**
+	 * @brief Target package's integrity will be checked
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_INTEGRITY_START,
+
+	/**
+	 * @brief Target package's integrity was checked
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_INTEGRITY_DONE,
+
+	/**
+	 * @brief Target deltas's integrity will be checked
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_DELTA_INTEGRITY_START,
+
+	/**
+	 * @brief Target delta's integrity was checked
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_DELTA_INTEGRITY_DONE,
+
+	/**
+	 * @brief Deltas will be applied to packages
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_DELTA_PATCHES_START,
+
+	/**
+	 * @brief Deltas were applied to packages
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_DELTA_PATCHES_DONE,
+
+	/**
+	 * @brief Delta patch will be applied to target package
+	 *
+	 * The filename of the package and the filename of the patch is  
passed to
+	 * the callback
+	 */
  	PM_TRANS_EVT_DELTA_PATCH_START,
+
+	/**
+	 * @brief Delta patch was applied to target package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_DELTA_PATCH_DONE,
+
+	/**
+	 * @brief Delta patch failed to apply to target package
+	 *
+	 * No paramaters are passed
+	 */
  	PM_TRANS_EVT_DELTA_PATCH_FAILED,
  	PM_TRANS_EVT_SCRIPTLET_INFO,
+
+	/**
+	 * @brief Print URI
+	 *
+	 * The database's URI and the package's filename are passed to the
+	 * callback
+	 */
  	PM_TRANS_EVT_PRINTURI,
+
+	/**
+	 * @brief Files will be downloaded from a repository
+	 *
+	 * The repository's tree name is passed to the callback
+	 */
  	PM_TRANS_EVT_RETRIEVE_START,
  } pmtransevt_t;
+/*@}*/

  /* Transaction Conversations (ie, questions) */
  typedef enum _pmtransconv_t {
-- 
1.5.4.5



--
Sebastian Nowicki