FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > ArchLinux > ArchLinux Pacman Development

 
 
LinkBack Thread Tools
 
Old 04-26-2008, 07:04 PM
Sebastian Nowicki
 
Default Add documentation for transaction events

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>
---
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
 
Old 04-26-2008, 07:17 PM
"Dan McGee"
 
Default Add documentation for transaction events

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
>

_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-26-2008, 07:19 PM
Sebastian Nowicki
 
Default Add documentation for transaction events

I didn't really know what PM_TRANS_EVT_SCRIPTLET_INFO is for, so I
didn't comment it. I glanced at the code but the function in which it
is sent is huge and it's late . Also when documenting
PM_TRANS_EVT_ADD_DONE I looked at the code and it seems like oldpkg is
always NULL when the event is sent, so I only documented newpkg.
Correct me if I'm wrong on this.

The patch is a bit lengthy, but it's very hard to use these events
without looking at the code. There was no way of telling what data
actually gets passed in without looking at code. I wasn't really sure
how to document it, so I just did it how I thought would be logical.

ps. I sent the patch from Mail.app so I hope it applies ok.

--
Sebastian Nowicki


_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 

Thread Tools




All times are GMT. The time now is 12:00 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org