X-Git-Url: http://gitweb.michael.orlitzky.com/?p=mailshears.git;a=blobdiff_plain;f=lib%2Fcommon%2Fdovecot_plugin.rb;h=213e99fd7bcf266b6b436430cad149394f623a65;hp=fa61d5367b593d959c1839de143f1f0c767490db;hb=df4e02ebf6a4e28a58abcb298a4442a245ad0b15;hpb=d0bfa37fb4be739b31dd97c493764ca19a160182

diff --git a/lib/common/dovecot_plugin.rb b/lib/common/dovecot_plugin.rb
index fa61d53..213e99f 100644
--- a/lib/common/dovecot_plugin.rb
+++ b/lib/common/dovecot_plugin.rb
@@ -3,20 +3,44 @@ require 'common/filesystem'
 require 'common/plugin'
 require 'common/user'
 
-
+# Code that all Dovecot plugins ({DovecotPrune}, {DovecotRm}, and
+# {DovecotMv}) will share.
+#
 module DovecotPlugin
-  # Code that all Dovecot plugins (Prune, Rm, Mv...) will
-  # share.  That is, we implement the Plugin interface.
+
+  # We implement the Plugin "interface."
   include Plugin
 
+
+  # Initialize this Dovecot {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
   def initialize(cfg)
     @domain_root = cfg.dovecot_mail_root
   end
 
+  # Describe the given Dovecot domain by its filesystem path. The
+  # domain need not exist to obtain its path.
+  #
+  # @param domain [Domain] the {Domain} object whose description we want.
+  #
+  # @return [String] a String giving the path under which this domain's
+  #   mailboxes would reside on the filesystem.
+  #
   def describe_domain(domain)
     return get_domain_path(domain)
   end
 
+
+  # Describe the given Dovecot user by its filesystem mailbox
+  # path. The user need not exist to obtain its mailbox path.
+  #
+  # @param user [User] the {User} object whose description we want.
+  #
+  # @return [String] a String giving the path where this user's
+  #   mailbox would reside on the filesystem.
+  #
   def describe_user(user)
     return get_user_path(user)
   end
@@ -24,25 +48,51 @@ module DovecotPlugin
 
   protected;
 
+  # Return the filesystem path for the given {Domain} object.
+  #
+  # @param domain [Domain] the {Domain} whose path we want.
+  #
+  # @return [String] the filesystem path where this domain's mail
+  #   would be located.
+  #
   def get_domain_path(domain)
-    # Return the filesystem path for the given domain.
-    # That is, the directory where its mail is stored.
-    # Only works if the domain directory exists!
     return File.join(@domain_root, domain.to_s())
   end
 
 
+  # Return the filesystem path of this {User}'s mailbox.
+  #
+  # @param user [User] the {User} whose mailbox path we want.
+  #
+  # @return [String] the filesystem path where this user's mail
+  #   would be located.
+  #
   def get_user_path(user)
-    # Return the filesystem path of this user's mailbox.
     domain_path = get_domain_path(user.domain())
     return File.join(domain_path, user.localpart())
   end
 
 
+  # Produce a list of domains that exist in the Dovecot mailstore.
+  #
+  # @return [Array<Domain>] an array of {Domain} objects that have
+  #   corresponding directories within the Dovecot mailstore.
+  #
   def list_domains()
     return Filesystem.get_subdirs(@domain_root).map{ |d| Domain.new(d) }
   end
 
+
+  # Produce a list of users belonging to the given *domains* in the
+  # Dovecot mailstore.
+  #
+  # @param domains [Array<Domain>] an array of {Domain} objects whose
+  #   users we'd like to find.
+  #
+  # @return [Array<User>] an array of {User} objects that have
+  #   corresponding directories within the Dovecot mailstore belonging
+  #   to the specified *domains*.
+  #
   def list_domains_users(domains)
     users = []
 
@@ -66,6 +116,11 @@ module DovecotPlugin
   end
 
 
+  # Produce a list of all users in the Dovecot mailstore.
+  #
+  # @return [Array<User>] a list of users who have mailbox directories
+  #   within the Dovecot mailstore.
+  #
   def list_users()
     domains = list_domains()
     users = list_domains_users(domains)