On Sat, Apr 26, 2008 at 2:04 PM, Sebastian Nowicki <sebnow@gmail.com> wrote:
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@gmail.com>
Wow, awesome++. Thank you for doing this. Two issues though- your mailer is wrapping lines meaning this patch doesn't apply cleanly- you can either set your mailer so it doesn't rewrap things, or try to get git-send-email working which always works for me and prevents any line wrap errrors. My only other concern is blowing up alpm.h unnecessarily, but I don't see too many other ways of doing this. Perhaps we can get rid of all the blank comment lines in each desc section? These:
+ *
And get rid of the @brief tag and just move each first-line comment to the first line of the comment block? Doxygen also stops the brief comment automatically at the first '.' char, so we probably need to add those and fill out the punctuation elsewhere. So in short, this:
+ /** + * @brief Dependencies will be computed for a package + * + * No paramaters are passed + */
becomes:
+ /** Dependencies will be computed for a package. + * No parameters are passed. + */
(brief moved up, blank lines killed, periods added, s/paramater/parameter/g) Documentation is awesome to have though, so I really appreciate you taking the time to get all this down and written up. -Dan
--- 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
_______________________________________________ pacman-dev mailing list pacman-dev@archlinux.org http://archlinux.org/mailman/listinfo/pacman-dev