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

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

diff --git a/lib/common/davical_plugin.rb b/lib/common/davical_plugin.rb
index 363e08ef298cfc402aaf051ad486fedd3f553323..8684cca9e830a5005e98ef82c7ac916f511decf6 100644 (file)
--- a/lib/common/davical_plugin.rb
+++ b/lib/common/davical_plugin.rb
@@ -1,11 +1,18 @@
 require 'common/plugin'
 require 'common/user'
 
+# Code that all DAViCal plugins ({DavicalPrune}, {DavicalRm}, and
+# {DavicalMv}) will share.
+#
 module DavicalPlugin
-  # Code that all Davical plugins (Prune, Rm, Mv...) will share.  That
-  # is, we implement the Plugin interface.
+
+  # We implement the Plugin "interface."
   include Plugin
 
+  # Initialize this DAViCal {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
   def initialize(cfg)
     @db_host = cfg.davical_dbhost
     @db_port = cfg.davical_dbport
@@ -17,17 +24,28 @@ module DavicalPlugin
   end
 
 
+  # Describe the given DAViCal user who is assumed to exist.
+  #
+  # @param user [User] the {User} object whose description we want.
+  #
+  # @return [String] a String describing the given *user* in terms
+  #   of his DAViCal "Principal ID".
+  #
   def describe_user(user)
     principal_id = self.get_principal_id(user)
     return "Principal ID: #{principal_id}"
   end
 
 
+  #
+  # Produce a list of DAViCal users.
+  #
+  # This method remains public for use in testing.
+  #
+  # @return [Array<User>] an array of {User} objects, one for each
+  #   user found in the DAViCal database.
+  #
   def list_users()
-    #
-    # Produce a list of DAViCal users. This is public because it's
-    # useful for testing.
-    #
     usernames = []
 
     connection = PGconn.connect(@db_host, @db_port, @db_opts, @db_tty,
@@ -48,6 +66,14 @@ module DavicalPlugin
 
   protected;
 
+
+  # Find the "Principal ID" of the given user.
+  #
+  # @param user [User] the user whose Principal ID we want.
+  #
+  # @return [Fixnum] an integer representing the user's Principal ID
+  #   that we obtained from the DAViCal database.
+  #
   def get_principal_id(user)
     principal_id = nil