[pacman-dev] [PATCH] Add documentation for transaction events
Dan McGee
dpmcgee at gmail.com
Sat Apr 26 15:17:14 EDT 2008
On Sat, Apr 26, 2008 at 2:04 PM, Sebastian Nowicki <sebnow at 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 at 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 at archlinux.org
> http://archlinux.org/mailman/listinfo/pacman-dev
>
More information about the pacman-dev
mailing list