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

[mailshears.git] / lib / rm / rm_plugin.rb

diff --git a/lib/rm/rm_plugin.rb b/lib/rm/rm_plugin.rb
index fd0c541a44cb25ed7ffbe7e96db3c19b59426265..ff165b4e8081c653c047276a5fb7045ba9a0d938 100644 (file)
--- a/lib/rm/rm_plugin.rb
+++ b/lib/rm/rm_plugin.rb
@@ -1,47 +1,76 @@
 require 'common/plugin.rb'
 
+#
+# Plugins for the removal of users and domains.
+#
 module RmPlugin
-  #
-  # Plugins for the removal of users.
-  #
 
+  # Absorb the subclass run() magic from the Plugin::Run module.
   extend Plugin::Run
 
+  # The runner class associated with removal plugins.
+  #
+  # @return [Class] the {RmRunner} class.
+  #
   def self.runner()
     return RmRunner
   end
 
+
+  # The "dummy" runner class associated with removal plugins.
+  #
+  # @return [Class] the {RmDummyRunner} class.
+  #
   def self.dummy_runner()
     return RmDummyRunner
   end
 
-  def delete(target)
-    # A generic version of delete_user/delete_domain that
+
+  # Remove the *target* domain or user. This is a generic version of
+  # the {#remove_user} and {#remove_domain} operations that will
+  # dispatch based on the type of *target*.
+  #
+  # @param target [User,Domain] the user or domain to remove.
+  #
+  def remove(target)
+    # A generic version of remove_user/remove_domain that
     # dispatches base on the class of the target.
     if target.is_a?(User)
-      return delete_user(target)
+      return remove_user(target)
     elsif target.is_a?(Domain)
-      return delete_domain(target)
+      return remove_domain(target)
     else
       raise NotImplementedError
     end
   end
 
-  def delete_domain(domain)
-    # Delete the given domain. Some plugins don't have a concept of
-    # domains, so just delete all users with a username that looks
-    # like it's in the given domain.
+
+  # Remove the given *domain*. Some plugins don't have a concept of
+  # domains, so the default implementation here removes all users that
+  # look like they belong to *domain*. Subclasses can be smarter.
+  #
+  # @param domain [Domain] the domain to remove.
+  #
+  def remove_domain(domain)
     users = list_domains_users([domain])
 
+    # It's possible for a domain to exist with no users, but this
+    # default implementation is based on the assumption that it should
+    # work for plugins having no "domain" concept.
     raise NonexistentDomainError.new(domain.to_s()) if users.empty?
 
     users.each do |u|
-      delete_user(u)
+      remove_user(u)
     end
   end
 
-  def delete_user(user)
-    # Delete the given user.
+
+  # The interface for the "remove a user" operation. Subclasses
+  # need to implement this method so that it removes *user*.
+  #
+  # @param user [User] the user to remove.
+  #
+  def remove_user(user)
     raise NotImplementedError
   end