dovecot-2.2: doveadm: Added comments to struct doveadm_mail_cmd_...

[dovecot at dovecot.org]

details:   http://hg.dovecot.org/dovecot-2.2/rev/111f19992c06
changeset: 18234:111f19992c06
user:      Timo Sirainen <tss at iki.fi>
date:      Mon Feb 09 15:21:55 2015 +0200
description:
doveadm: Added comments to struct doveadm_mail_cmd_vfuncs

diffstat:

 src/doveadm/doveadm-mail.h |  22 +++++++++++++++++++++-
 1 files changed, 21 insertions(+), 1 deletions(-)

diffs (42 lines):

diff -r acebb486714e -r 111f19992c06 src/doveadm/doveadm-mail.h
--- a/src/doveadm/doveadm-mail.h	Mon Feb 09 13:03:47 2015 +0200
+++ b/src/doveadm/doveadm-mail.h	Mon Feb 09 15:21:55 2015 +0200
@@ -15,17 +15,37 @@
 struct doveadm_mail_cmd_context;
 
 struct doveadm_mail_cmd_vfuncs {
-	bool (*parse_arg)(struct doveadm_mail_cmd_context *ctx,int c);
+	/* Parse one getopt() parameter. This is called for each parameter. */
+	bool (*parse_arg)(struct doveadm_mail_cmd_context *ctx, int c);
+	/* Usually not needed. The preinit() is called just after parsing all
+	   parameters, but before any userdb lookups are done. This allows the
+	   preinit() to alter the userdb lookup behavior (especially
+	   service_flags). */
 	void (*preinit)(struct doveadm_mail_cmd_context *ctx);
+	/* Initialize the command. Most importantly if the function prints
+	   anything, this should initialize the headers. It shouldn't however
+	   do any actual work. The init() is called also when doveadm is
+	   performing the work via doveadm-server, which could be running
+	   remotely with completely different Dovecot configuration. */
 	void (*init)(struct doveadm_mail_cmd_context *ctx,
 		     const char *const args[]);
+	/* Usually not needed. When iterating through multiple users, use this
+	   function to get the next username. Overriding this is usually done
+	   only when there's a known username filter, such as the expire
+	   plugin. */
 	int (*get_next_user)(struct doveadm_mail_cmd_context *ctx,
 			     const char **username_r);
+	/* Usually not needed. This is called between
+	   mail_storage_service_lookup() and mail_storage_service_next() for
+	   each user. */
 	int (*prerun)(struct doveadm_mail_cmd_context *ctx,
 		      struct mail_storage_service_user *service_user,
 		      const char **error_r);
+	/* This is the main function which performs all the work for the
+	   command. This is called once per each user. */
 	int (*run)(struct doveadm_mail_cmd_context *ctx,
 		   struct mail_user *mail_user);
+	/* Deinitialize the command. Called once at the end. */
 	void (*deinit)(struct doveadm_mail_cmd_context *ctx);
 };