From aebdf12adce2766e2957f88916fcae6374d4eb4b Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Fri, 6 Nov 2015 09:55:02 -0500
Subject: [PATCH] Begin updating docs; remove two unused exit codes.

---
 lib/common/errors.rb     | 28 +++++++++++-----------------
 lib/common/exit_codes.rb |  7 ++++---
 lib/common/filesystem.rb | 24 ++++++++++++++++++++++--
 lib/mailshears.rb        |  5 ++---
 4 files changed, 39 insertions(+), 25 deletions(-)

diff --git a/lib/common/errors.rb b/lib/common/errors.rb
index 6a9927a..7e2bd50 100644
--- a/lib/common/errors.rb
+++ b/lib/common/errors.rb
@@ -1,21 +1,15 @@
-# Username is syntactically invalid.
-class InvalidUserError < StandardError
-end
+# An error indicating that a username is syntactically invalid.
+class InvalidUserError < StandardError; end
 
-# Domain is syntactically invalid.
-class InvalidDomainError < StandardError
-end
+# An error indicating that a domain is syntactically invalid.
+class InvalidDomainError < StandardError; end
 
+# An error indicating that a user does not exist.
+class NonexistentUserError < StandardError; end
 
-# Used to indicate that an user does not exist.
-class NonexistentUserError < StandardError
-end
+# An error indicating that a domain does not exist.
+class NonexistentDomainError < StandardError; end
 
-# Used to indicate that a domain does not exist.
-class NonexistentDomainError < StandardError
-end
-
-
-# When you try to rename a user on top of one that already exists.
-class UserAlreadyExistsError < StandardError
-end
+# An error indicating that some user already exists. For example, if
+# one tries to rename a user and the destination user already exists.
+class UserAlreadyExistsError < StandardError; end
diff --git a/lib/common/exit_codes.rb b/lib/common/exit_codes.rb
index a81067b..b7928a7 100644
--- a/lib/common/exit_codes.rb
+++ b/lib/common/exit_codes.rb
@@ -1,6 +1,7 @@
 module ExitCodes
+  # Everything went better than expected.
   SUCCESS = 0
-  FILESYSTEM_ERROR = 1
-  DATABASE_ERROR = 2
-  BAD_COMMAND_LINE = 3
+
+  # The command-line arguments were not what we expected.
+  BAD_COMMAND_LINE = 1
 end
diff --git a/lib/common/filesystem.rb b/lib/common/filesystem.rb
index 72ff901..b44e52c 100644
--- a/lib/common/filesystem.rb
+++ b/lib/common/filesystem.rb
@@ -1,16 +1,36 @@
 class Filesystem
+  # Convenience methods for working with the filesystem. This class
+  # only provides static methods, to be used analogously to the File
+  # class (for example, File.directory?).
 
-  def self.begins_with_dot(path)
+
+  # Return whether or not the given path begins with a dot (ASCII
+  # period).
+  #
+  # @param path [String] the path whose first character you want to check.
+  #
+  # @return [Boolean] whether or not *path* begins with an ASCII period.
+  #
+  def self.begins_with_dot?(path)
     return (path[0..0] == '.')
   end
 
+
+  # Get a list of all real subdirectories of the given directory.
+  #
+  # @param dir [String] the directory whose subdirectories you want.
+  #
+  # @return [Array<String>] a list of subdirectories of *dir*, not
+  #   including the pseudo-directories "." and ".." (the current/parent
+  #   directories).
+  #
   def self.get_subdirs(dir)
     subdirs = []
 
     Dir.open(dir) do |d|
       d.each do |entry|
         relative_path = File.join(dir, entry)
-        if (File.directory?(relative_path) and not begins_with_dot(entry))
+        if File.directory?(relative_path) and not self.begins_with_dot?(entry)
           subdirs << entry
         end
       end
diff --git a/lib/mailshears.rb b/lib/mailshears.rb
index e5f2e6e..55a87f8 100644
--- a/lib/mailshears.rb
+++ b/lib/mailshears.rb
@@ -1,6 +1,5 @@
-# Load the rest of the code we'll use. This loads only what we'll need
-# in the executable. The library files are supposed to require what
-# they need.
+# Load only the files needed by our executable. The library files are
+# supposed to require what they need themselves.
 
 require 'common/configuration'
 require 'common/errors'
-- 
2.43.2