X-Git-Url: http://gitweb.michael.orlitzky.com/?p=mailshears.git;a=blobdiff_plain;f=lib%2Fcommon%2Fdomain.rb;h=a9e544053808857ef8cd7b1987cea95319247dd5;hp=ec4fecf35ee579cda7be81abbf8e50a9ec6f2ce5;hb=5bf27259563a3dda6425dc794722273cc29b69f7;hpb=30e96ed6093c479e7605b23a68aba7da11297679

diff --git a/lib/common/domain.rb b/lib/common/domain.rb
index ec4fecf..a9e5440 100644
--- a/lib/common/domain.rb
+++ b/lib/common/domain.rb
@@ -1,9 +1,21 @@
 require 'common/errors'
 
+# A class representing a syntactically valid domain. Essentially, the
+# part after the "@" in an email address. Once constructed, you can be
+# sure that it's valid.
+#
 class Domain
 
+  # @domain contains the String representation of this domain.
   @domain = nil
 
+
+  # Initialize this Domain object. If the domain is invalid, then an
+  # {InvalidDomainError} will be raised containing the reason
+  # why the domain is invalid.
+  #
+  # @param domain [String] the string representation of this domain.
+  #
   def initialize(domain)
     if domain.empty? then
       msg = "domain cannot be empty"
@@ -13,14 +25,39 @@ class Domain
     @domain = domain
   end
 
+
+  # Convert this domain to a String.
+  #
+  # @return [String] the string representation of this Domain.
+  #
   def to_s()
     return @domain
   end
 
+
+  # Check if this Domain is equal to some other Domain. The comparison
+  # is based on their String representations.
+  #
+  # @param other [Domain] the Domain object to compare me to.
+  #
+  # @return [Boolean] If *self* and *other* have equal String
+  #   representations, then true is returned. Otherwise, false is
+  #   returned.
+  #
   def ==(other)
     return self.to_s() == other.to_s()
   end
 
+
+  # Compare two Domain objects for sorting purposes. The comparison
+  # is based on their String representations.
+  #
+  # @param other [Domain] the Domain object to compare me to.
+  #
+  # @return [0,1,-1] a trinary indicator of how *self* relates to *other*,
+  #   obtained by performing the same comparison on the String
+  #   representations of *self* and *other*.
+  #
   def <=>(other)
     return self.to_s() <=> other.to_s()
   end