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

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

diff --git a/lib/common/user.rb b/lib/common/user.rb
index f67d0443da1180fa2b9ffc3778542b0e0feb8bf4..a5d3559c970b64af6611549847e28885969bc1ed 100644 (file)
--- a/lib/common/user.rb
+++ b/lib/common/user.rb
@@ -1,25 +1,46 @@
 require 'common/domain'
 require 'common/errors'
 
+# A class representing a syntactically valid user; that is, an email
+# address. Once constructed, you can be sure that it's valid.
+#
 class User
-  # A class representing a syntactically valid user; that is, an email
-  # address. Once constructed, you can be sure that it's valid.
 
+  # @localpart is a String containing the "user" part of "user@domain".
   @localpart = nil
+
+  # @domain contains a {Domain} object representing the domain part of
+  # "user@domain".
   @domain = nil
 
+
+  # Obtain the {Domain} object corresponding to this User.
+  #
+  # @return [Domain] the domain corresponding to this User.
+  #
   def domain()
     return @domain
   end
 
+
+  # Obtain the domain part of this User object as a string.
+  #
+  # @return [String] a String representation of this User's domain.
+  #
   def domainpart()
     return @domain.to_s()
   end
 
+
+  # Initialize this User object. If either of the local/domain parts
+  # is invalid, then either an {InvalidUserError} or an {InvalidDomainError}
+  # will be raised containing the reason why that part is invalid.
+  #
+  # @param username [String] an email address from which to construct
+  #   this User.
+  #
   def initialize(username)
-    # Initialize this user object, but throw an error if either the
-    # localpart or domainpart are invalid. The one argument is an
-    # email address string.
+
     if not username.is_a?(String)
       msg =  'username must be a String '
       msg += "but a #{username.class.to_s()} was given"
@@ -49,18 +70,50 @@ class User
     @domain = Domain.new(parts[1])
   end
 
+
+  # Obtain the "user" part of this User object as a String.
+  #
+  # @return [String] the "user" part of this User's "user@domain"
+  #   address.
+  #
   def localpart()
     return @localpart
   end
 
+
+  # Convert this User to an email address string.
+  #
+  # @return [String] an email address String constructed from this
+  #   user's local and domain parts.
+  #
   def to_s()
     return @localpart + '@' + @domain.to_s()
   end
 
+
+  # Check if this User is equal to some other User. The comparison
+  # is based on their String representations.
+  #
+  # @param other [User] the User 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 User objects for sorting purposes. The comparison is
+  # is based on their String representations.
+  #
+  # @param other [User] the User 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