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:42 PM
Sebastian Nowicki
 
Default Add documentation for transaction events

On 27/04/2008, at 3:17 AM, Dan McGee wrote:
>
> 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.

Sorry, this was the first time I posted a patch from Mail.app, didn't
know it did that.

> My only other concern is blowing up alpm.h
> unnecessarily, but I don't see too many other ways of doing this.

Could the enum definition be moved to trans.c and have just the
typedef in alpm.h, as is done with __pmdb_t, etc.? I haven't really
used enums before so I don't know if it would stay in scope.

> Perhaps we can get rid of all the blank comment lines in each desc
> section? These:
>> + *

It appears not. From the doxygen manual:
> One could use the rief command with one of the above comment
> blocks. This command ends at the end of a paragraph, so the detailed
> description follows after an empty line.
I tried removing the blank line but the detailed description just
ended up being on the same line.

--
Sebastian Nowicki


_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-26-2008, 11:21 PM
Miklos Vajna
 
Default Add documentation for transaction events

On Sun, Apr 27, 2008 at 03:19:11AM +0800, Sebastian Nowicki <sebnow@gmail.com> wrote:
> I didn't really know what PM_TRANS_EVT_SCRIPTLET_INFO is for, so I

the lib can send 3 types of scriptlet events:

2 of them is for "doing something... done."
(PM_TRANS_EVT_SCRIPTLET_START, PM_TRANS_EVT_SCRIPTLET_DONE)

the third is for everything else, that's PM_TRANS_EVT_SCRIPTLET_INFO.

basically if you don't do an "echo START <event desc>" or "echo DONE <ret
code>", then the frontend will get the string via a
PM_TRANS_EVT_SCRIPTLET_INFO.
_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-27-2008, 05:29 AM
Sebastian Nowicki
 
Default Add documentation for transaction events

I thought that I sent this yesterday, but it seems sendmail wasn't set
up properly. I added documentation for PM_TRANS_EVT_SCRIPTLET_INFO, but
I'm still not sure if it's correct.

_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-27-2008, 05:29 AM
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 | 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


_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-27-2008, 09:03 AM
Xavier
 
Default Add documentation for transaction events

Sebastian Nowicki wrote:
> +
> + /** Package waas extracted
> + *
> + * No parameters are passed
> + */
> PM_TRANS_EVT_EXTRACT_DONE,

s/waas/was

> +
> + /** Target deltas's integrity will be checked
> + *
> + * No parameters are passed
> + */
> PM_TRANS_EVT_DELTA_INTEGRITY_START,

Shouldn't it be deltas' or something? Not even sure


Except these two typos, it looks alright. I just had the same first
impression as Dan, it looks a bit intrusive. Though you already removed
one line from the original patch, but too bad we can't remove more.

I was thinking, do we really need to specify "No parameters are passed"
every time? Maybe having no description could implicitly means that no
parameters are passed.

_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-27-2008, 10:20 AM
Sebastian Nowicki
 
Default Add documentation for transaction events

On 27/04/2008, at 5:03 PM, Xavier wrote:
> Sebastian Nowicki wrote:
>> +
>> + /** Package waas extracted
>> + *
>> + * No parameters are passed
>> + */
>> PM_TRANS_EVT_EXTRACT_DONE,
>
> s/waas/was
>
>> +
>> + /** Target deltas's integrity will be checked
>> + *
>> + * No parameters are passed
>> + */
>> PM_TRANS_EVT_DELTA_INTEGRITY_START,
>
> Shouldn't it be deltas' or something? Not even sure

Yes, deltas', damn typos :P

>
> Except these two typos, it looks alright. I just had the same first
> impression as Dan, it looks a bit intrusive. Though you already
> removed
> one line from the original patch, but too bad we can't remove more.
>
> I was thinking, do we really need to specify "No parameters are
> passed"
> every time? Maybe having no description could implicitly means that no
> parameters are passed.

For documentation I think explicit is better than implicit. Someone
could assume that it's simply not documented. Though I was thinking,
maybe "NULL parameters are passed" or something would be better. We
could just say "NULL parameters are passed unless specified otherwise"
in the documentation of the enum itself. Although the enum's brief
doesn't seem to show up anywhere...

--
Sebastian Nowicki


_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-27-2008, 10:54 AM
Sebastian Nowicki
 
Default Add documentation for transaction events

This is probably as good as it will get. I fixed the typos, and removed
the "No parameters..." lines. The enum documentation was wrong as well,
the brief actually added to the group's description, so I fixed that
too. The enum description now explicitely states that null parameters
are passed unless specified otherwise. Empty lines between comments were
removed to slim it down a bit, I don't think it really makes them any
harder to read.

_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-27-2008, 10:54 AM
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 | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++ +-
1 files changed, 71 insertions(+), 1 deletions(-)

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

-/* Transaction Events */
+/**
+ * @addtogroup alpm_trans
+ * @{
+ */
+/**
+ * @brief Transaction events
+ *
+ * NULL parameters are passed to in all events unless specified
+ * otherwise.
+ */
typedef enum _pmtransevt_t {
+ /** Dependencies will be computed for a package */
PM_TRANS_EVT_CHECKDEPS_START = 1,
+ /** Dependencies were computed for a package */
PM_TRANS_EVT_CHECKDEPS_DONE,
+ /** File conflicts will be computed for a package */
PM_TRANS_EVT_FILECONFLICTS_START,
+ /** File conflicts were computed for a package */
PM_TRANS_EVT_FILECONFLICTS_DONE,
+ /** Dependencies will be resolved for target package */
PM_TRANS_EVT_RESOLVEDEPS_START,
+ /** Dependencies were resolved for target package */
PM_TRANS_EVT_RESOLVEDEPS_DONE,
+ /** Inter-conflicts will be checked for target package */
PM_TRANS_EVT_INTERCONFLICTS_START,
+ /** Inter-conflicts were checked for target package */
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 */
PM_TRANS_EVT_EXTRACT_DONE,
+ /** Target package's integrity will be checked */
PM_TRANS_EVT_INTEGRITY_START,
+ /** Target package's integrity was checked */
PM_TRANS_EVT_INTEGRITY_DONE,
+ /** Target deltas's integrity will be checked */
PM_TRANS_EVT_DELTA_INTEGRITY_START,
+ /** Target delta's integrity was checked */
PM_TRANS_EVT_DELTA_INTEGRITY_DONE,
+ /** Deltas will be applied to packages */
PM_TRANS_EVT_DELTA_PATCHES_START,
+ /** Deltas were applied to packages */
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 */
PM_TRANS_EVT_DELTA_PATCH_DONE,
+ /** Delta patch failed to apply to target package */
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


_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-28-2008, 06:43 AM
Xavier
 
Default Add documentation for transaction events

On Sun, Apr 27, 2008 at 12:54 PM, Sebastian Nowicki <sebnow@gmail.com> wrote:
>
> This is probably as good as it will get. I fixed the typos, and removed
> the "No parameters..." lines. The enum documentation was wrong as well,
> the brief actually added to the group's description, so I fixed that
> too. The enum description now explicitely states that null parameters
> are passed unless specified otherwise. Empty lines between comments were
> removed to slim it down a bit, I don't think it really makes them any
> harder to read.
>

Good job, I like it!

_______________________________________________
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 10:03 PM.

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