Document everything with YARD and fix some bugs along the way.

[mailshears.git] / lib / common / dovecot_plugin.rb

diff --git a/lib/common/dovecot_plugin.rb b/lib/common/dovecot_plugin.rb
index fa61d5367b593d959c1839de143f1f0c767490db..213e99fd7bcf266b6b436430cad149394f623a65 100644 (file)
--- 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'
 
 require 'common/plugin'
 require 'common/user'
 

-
+# Code that all Dovecot plugins ({DovecotPrune}, {DovecotRm}, and
+# {DovecotMv}) will share.
+#

 module DovecotPlugin
 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
 
   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
 
   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
 
   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
   def describe_user(user)
     return get_user_path(user)
   end


@@ -24,25 +48,51 @@ module DovecotPlugin
 
   protected;
 
 
   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)
   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 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)
   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
 
 
     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
 
   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 = []
 
   def list_domains_users(domains)
     users = []
 


@@ -66,6 +116,11 @@ module DovecotPlugin
   end
 
 
   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)
   def list_users()
     domains = list_domains()
     users = list_domains_users(domains)