[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 |  144 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 143 insertions(+), 1 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index a7ea063..fc898b0 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -283,36 +283,178 @@ typedef enum _pmtransflag_t {
 	PM_TRANS_FLAG_RECURSEALL = 0x10000
 } pmtransflag_t;
 
-/* Transaction Events */
+/**
+ * @addtogroup alpm_trans
+ * @brief Transaction events
+ */
+/*@{*/
 typedef enum _pmtransevt_t {
+	/** Dependencies will be computed for a package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_CHECKDEPS_START = 1,
+
+	/** Dependencies were computed for a package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_CHECKDEPS_DONE,
+
+	/** File conflicts will be computed for a package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_FILECONFLICTS_START,
+
+	/** File conflicts were computed for a package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_FILECONFLICTS_DONE,
+
+	/** Dependencies will be resolved for target package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_RESOLVEDEPS_START,
+
+	/** Dependencies were resolved for target package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_RESOLVEDEPS_DONE,
+
+	/** Inter-conflicts will be checked for target package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_INTERCONFLICTS_START,
+
+	/** Inter-conflicts were checked for target package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_INTERCONFLICTS_DONE,
+
+	/** Package will be installed
+	 *
+	 * A pointer to the target package is passed to the callback
+	 */
 	PM_TRANS_EVT_ADD_START,
+
+	/** Package was installed
+	 *
+	 * A pointer to the new package is passed to the callback
+	 */
 	PM_TRANS_EVT_ADD_DONE,
+
+	/** Package will be removed
+	 *
+	 * A pointer to the target package is passed to the callback
+	 */
 	PM_TRANS_EVT_REMOVE_START,
+
+	/** Package was removed
+	 *
+	 * A pointer to the removed package is passed to the callback
+	 */
 	PM_TRANS_EVT_REMOVE_DONE,
+
+	/** Package will be upgraded
+	 *
+	 * A pointer to the upgraded package is passed to the callback
+	 */
 	PM_TRANS_EVT_UPGRADE_START,
+
+	/** 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,
+
+	/** Package waas extracted
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_EXTRACT_DONE,
+
+	/** Target package's integrity will be checked
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_INTEGRITY_START,
+
+	/** Target package's integrity was checked
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_INTEGRITY_DONE,
+
+	/** Target deltas's integrity will be checked
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_DELTA_INTEGRITY_START,
+
+	/** Target delta's integrity was checked
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_DELTA_INTEGRITY_DONE,
+
+	/** Deltas will be applied to packages
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_DELTA_PATCHES_START,
+
+	/** Deltas were applied to packages
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_DELTA_PATCHES_DONE,
+
+	/** 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,
+
+	/** Delta patch was applied to target package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_DELTA_PATCH_DONE,
+
+	/** Delta patch failed to apply to target package
+	 *
+	 * No parameters are passed
+	 */
 	PM_TRANS_EVT_DELTA_PATCH_FAILED,
+
+	/** Scriptlet has printed information
+	 *
+	 * A line of text is passed to the callback
+	 */
 	PM_TRANS_EVT_SCRIPTLET_INFO,
+
+	/** Print URI
+	 *
+	 * The database's URI and the package's filename are passed to the
+	 * callback
+	 */
 	PM_TRANS_EVT_PRINTURI,
+
+	/** 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