app/models/email_address.rb in has_emails-0.1.2 vs app/models/email_address.rb in has_emails-0.1.3

@@ -1,6 +1,19 @@
-# Represents a valid RFC822 email address
+# Represents a valid RFC822 email address.  See http://www.w3.org/Protocols/rfc822/
+# for more information about the entire specification.
+# 
+# Email addresses are directly associated with emails and, therefore, should be
+# used for building and delivering new e-mails.
+# 
+# == Associations
+# 
+# Email addresses have the following associations defined as a result of using the
+# +has_emails+ macro:
+# * +emails+ - Emails that were composed and are visible to the owner.  Emails may have been sent or unsent.
+# * +received_emails+ - Emails that have been received from others and are visible.  Emails may have been read or unread.
+# * +unsent_emails+ - Emails that have not yet been delivered
+# * +sent_emails+ - Emails that have already been delivered
 class EmailAddress < ActiveRecord::Base
   has_emails
   
   validates_presence_of       :spec
   validates_as_email_address  :spec
@@ -12,10 +25,13 @@
     def find_or_create_by_address(address)
       name, spec = split_address(address)
       find_or_create_by_name_and_spec(name, spec)
     end
     
-    # Splits the given address into a name and spec
+    # Splits the given address into a name and spec. For example,
+    # 
+    #   EmailAddress.split_address("John Smith <[e-mail]")  # => ["John Smith", "[e-mail]"]
+    #   EmailAddress.split_address("[e-mail]")              # => [nil, "[e-mail]"]
     def split_address(address)
       if match = /^(\S.*)\s+<(.*)>$/.match(address)
         name = match[1]
         spec = match[2]
       else