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

diff --git a/lib/common/dovecot_plugin.rb b/lib/common/dovecot_plugin.rb
index 4718483..213e99f 100644
--- a/lib/common/dovecot_plugin.rb
+++ b/lib/common/dovecot_plugin.rb
@@ -3,62 +3,96 @@ 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.mail_root
+    @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)
-    begin
-      domain_path = get_domain_path(domain)
-      return domain_path
-    rescue NonexistentDomainError => e
-      return "Doesn't exist: #{e.to_s}"
-    end
-  end
-
-  def describe_user(user)
-    begin
-      user_path = get_user_path(user)
-      return user_path
-    rescue NonexistentUserError => e
-      return "Doesn't exist: #{e.to_s}"
-    end
+    return get_domain_path(domain)
   end
 
 
-  def domain_exists(domain)
-    domains = list_domains()
-    return domains.include?(domain)
+  # 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
 
 
   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 = []
 
@@ -82,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)