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

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

diff --git a/lib/common/roundcube_plugin.rb b/lib/common/roundcube_plugin.rb
index 948a5b91b5577dc5ebd3c45e24ad150b99556c97..031e3f9ddd725e6b2bc427a323e567c1291300e3 100644 (file)
--- a/lib/common/roundcube_plugin.rb
+++ b/lib/common/roundcube_plugin.rb
@@ -1,11 +1,19 @@
 require 'common/plugin'
 require 'common/user'
 
+# Code that all Roundcube plugins ({RoundcubePrune}, {RoundcubeRm},
+# {RoundcubeMv}) share.
+#
 module RoundcubePlugin
-  # Code that all Roundcube plugins (Prune, Rm, Mv...) will share.
-  # That is, we implement the Plugin interface.
+
+  # We implement the Plugin "interface."
   include Plugin
 
+
+  # Initialize this Roundcube {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
   def initialize(cfg)
     @db_host = cfg.roundcube_dbhost
     @db_port = cfg.roundcube_dbport
@@ -17,15 +25,25 @@ module RoundcubePlugin
   end
 
 
+  # Describe the given Roundcube *user*.
+  #
+  # @param user [User] the user whose description we want.
+  #
+  # @return [String] a string containing the Roundcube "User ID"
+  #   associated with *user*.
+  #
   def describe_user(user)
     user_id = self.get_user_id(user)
     return "User ID: #{user_id}"
   end
 
 
+  # Return a list of Roundcube users.
+  #
+  # @return [Array<User>] a list of users contained in the
+  #   Roundcube database.
+  #
   def list_users()
-    # Produce a list of Roundcube users. This is used in prune/rm, and
-    # is public because it is useful in testing.
     usernames = []
 
     connection = PGconn.connect(@db_host, @db_port, @db_opts, @db_tty,
@@ -43,6 +61,13 @@ module RoundcubePlugin
 
   protected;
 
+
+  # Find the Roundcube "User ID" associated with the given *user*.
+  #
+  # @param user [User] the user whose Roundcube "User ID" we want.
+  #
+  # @return [Fixnum] the Roundcube "User ID" for *user*.
+  #
   def get_user_id(user)
     user_id = nil