Big documentation upgrade for ARes (closes #8694) [jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7098 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 135 insertions, 8 deletions

diff --git a/activeresource/lib/active_resource/validations.rb b/activeresource/lib/active_resource/validations.rb
index 76aa7d2f00..57d2ae559d 100644
--- a/activeresource/lib/active_resource/validations.rb
+++ b/activeresource/lib/active_resource/validations.rb
@@ -14,23 +14,76 @@ module ActiveResource
       @base, @errors = base, {}
     end
 
+    # Add an error to the base Active Resource object rather than an attribute.
+    #
+    # ==== Examples
+    #   my_folder = Folder.find(1)
+    #   my_folder.errors.add_to_base("You can't edit an existing folder")
+    #   my_folder.errors.on_base
+    #   # => "You can't edit an existing folder"
+    #
+    #   my_folder.errors.add_to_base("This folder has been tagged as frozen")
+    #   my_folder.valid?
+    #   # => false
+    #   my_folder.errors.on_base
+    #   # => ["You can't edit an existing folder", "This folder has been tagged as frozen"]
+    #
     def add_to_base(msg)
       add(:base, msg)
     end
 
+    # Adds an error to an Active Resource object's attribute (named for the +attribute+ parameter)
+    # with the error message in +msg+.
+    #
+    # ==== Examples
+    #   my_resource = Node.find(1)
+    #   my_resource.errors.add('name', 'can not be "base"') if my_resource.name == 'base'
+    #   my_resource.errors.on('name')
+    #   # => 'can not be "base"!'
+    #
+    #   my_resource.errors.add('desc', 'can not be blank') if my_resource.desc == ''
+    #   my_resource.valid?
+    #   # => false
+    #   my_resource.errors.on('desc')
+    #   # => 'can not be blank!'
+    #
     def add(attribute, msg)
       @errors[attribute.to_s] = [] if @errors[attribute.to_s].nil?
       @errors[attribute.to_s] << msg
     end
 
     # Returns true if the specified +attribute+ has errors associated with it.
+    #
+    # ==== Examples
+    #   my_resource = Disk.find(1)
+    #   my_resource.errors.add('location', 'must be Main') unless my_resource.location == 'Main'
+    #   my_resource.errors.on('location')
+    #   # => 'must be Main!'
+    #
+    #   my_resource.errors.invalid?('location')
+    #   # => true
+    #   my_resource.errors.invalid?('name')
+    #   # => false
     def invalid?(attribute)
       !@errors[attribute.to_s].nil?
     end
 
-    # * Returns nil, if no errors are associated with the specified +attribute+.
-    # * Returns the error message, if one error is associated with the specified +attribute+.
-    # * Returns an array of error messages, if more than one error is associated with the specified +attribute+.
+    # A method to return the errors associated with +attribute+, which returns nil, if no errors are 
+    # associated with the specified +attribute+, the error message if one error is associated with the specified +attribute+,
+    # or an array of error messages if more than one error is associated with the specified +attribute+.
+    #
+    # ==== Examples
+    #   my_person = Person.new(params[:person])
+    #   my_person.errors.on('login')
+    #   # => nil
+    #
+    #   my_person.errors.add('login', 'can not be empty') if my_person.login == ''
+    #   my_person.errors.on('login')
+    #   # => 'can not be empty'
+    #
+    #   my_person.errors.add('login', 'can not be longer than 10 characters') if my_person.login.length > 10
+    #   my_person.errors.on('login')
+    #   # => ['can not be empty', 'can not be longer than 10 characters']
     def on(attribute)
       errors = @errors[attribute.to_s]
       return nil if errors.nil?
@@ -39,23 +92,72 @@ module ActiveResource
     
     alias :[] :on
 
-    # Returns errors assigned to base object through add_to_base according to the normal rules of on(attribute).
+    # A method to return errors assigned to +base+ object through add_to_base, which returns nil, if no errors are 
+    # associated with the specified +attribute+, the error message if one error is associated with the specified +attribute+,
+    # or an array of error messages if more than one error is associated with the specified +attribute+.
+    #
+    # ==== Examples
+    #   my_account = Account.find(1)
+    #   my_account.errors.on_base
+    #   # => nil
+    #
+    #   my_account.errors.add_to_base("This account is frozen")
+    #   my_account.errors.on_base
+    #   # => "This account is frozen"
+    #
+    #   my_account.errors.add_to_base("This account has been closed")
+    #   my_account.errors.on_base
+    #   # => ["This account is frozen", "This account has been closed"]
+    #
     def on_base
       on(:base)
     end
 
     # Yields each attribute and associated message per error added.
+    #
+    # ==== Examples
+    #   my_person = Person.new(params[:person])
+    #
+    #   my_person.errors.add('login', 'can not be empty') if my_person.login == ''
+    #   my_person.errors.add('password', 'can not be empty') if my_person.password == ''
+    #   messages = ''
+    #   my_person.errors.each {|attr, msg| messages += attr.humanize + " " + msg + "<br />"}
+    #   messages
+    #   # => "Login can not be empty<br />Password can not be empty<br />"
+    #
     def each
       @errors.each_key { |attr| @errors[attr].each { |msg| yield attr, msg } }
     end
 
     # Yields each full error message added. So Person.errors.add("first_name", "can't be empty") will be returned
     # through iteration as "First name can't be empty".
+    #
+    # ==== Examples
+    #   my_person = Person.new(params[:person])
+    #
+    #   my_person.errors.add('login', 'can not be empty') if my_person.login == ''
+    #   my_person.errors.add('password', 'can not be empty') if my_person.password == ''
+    #   messages = ''
+    #   my_person.errors.each_full {|msg| messages += msg + "<br/>"}
+    #   messages
+    #   # => "Login can not be empty<br />Password can not be empty<br />"
+    #
     def each_full
       full_messages.each { |msg| yield msg }
     end
 
     # Returns all the full error messages in an array.
+    #
+    # ==== Examples
+    #   my_person = Person.new(params[:person])
+    #
+    #   my_person.errors.add('login', 'can not be empty') if my_person.login == ''
+    #   my_person.errors.add('password', 'can not be empty') if my_person.password == ''
+    #   messages = ''
+    #   my_person.errors.full_messages.each {|msg| messages += msg + "<br/>"}
+    #   messages
+    #   # => "Login can not be empty<br />Password can not be empty<br />"
+    #
     def full_messages
       full_messages = []
 
@@ -79,6 +181,17 @@ module ActiveResource
 
     # Returns the total number of errors added. Two errors added to the same attribute will be counted as such
     # with this as well.
+    #
+    # ==== Examples
+    #   my_person = Person.new(params[:person])
+    #   my_person.errors.size
+    #   # => 0
+    #
+    #   my_person.errors.add('login', 'can not be empty') if my_person.login == ''
+    #   my_person.errors.add('password', 'can not be empty') if my_person.password == ''
+    #   my_person.error.size
+    #   # => 2
+    #
     def size
       @errors.values.inject(0) { |error_count, attribute| error_count + attribute.size }
     end
@@ -86,6 +199,7 @@ module ActiveResource
     alias_method :count, :size
     alias_method :length, :size
     
+    # Grabs errors from the XML response.
     def from_xml(xml)
       clear
       humanized_attributes = @base.attributes.keys.inject({}) { |h, attr_name| h.update(attr_name.humanize => attr_name) }
@@ -102,9 +216,12 @@ module ActiveResource
     end
   end
   
-  # Module to allow validation of ActiveResource objects, which are implemented by overriding +Base#validate+ or its variants. 
-  # Each of these methods can inspect the state of the object, which usually means ensuring that a number of 
-  # attributes have a certain value (such as not empty, within a given range, matching a certain regular expression). For example:
+  # Module to allow validation of ActiveResource objects, which creates an Errors instance for every resource.
+  # Methods are implemented by overriding +Base#validate+ or its variants   Each of these methods can inspect 
+  # the state of the object, which usually means  ensuring that a number of attributes have a certain value 
+  # (such as not empty, within a given range, matching a certain regular expression and so on).
+  #
+  # ==== Example
   #
   #   class Person < ActiveResource::Base
   #      self.site = "http://www.localhost.com:3000/"
@@ -133,7 +250,6 @@ module ActiveResource
   #   person.attributes = { "last_name" => "Halpert", "phone_number" => "555-5555" }
   #   person.save                         # => true (and person is now saved to the remote service)
   #
-  # An Errors object is automatically created for every resource.
   module Validations
     def self.included(base) # :nodoc:
       base.class_eval do
@@ -141,6 +257,7 @@ module ActiveResource
       end
     end
 
+    # Validate a resource and save (POST) it to the remote web service.
     def save_with_validation
       save_without_validation
       true
@@ -149,6 +266,16 @@ module ActiveResource
       false
     end
 
+    # Checks for errors on an object (i.e., is resource.errors empty?).
+    # 
+    # ==== Examples
+    #   my_person = Person.create(params[:person])
+    #   my_person.valid?
+    #   # => true
+    #
+    #   my_person.errors.add('login', 'can not be empty') if my_person.login == ''
+    #   my_person.valid?
+    #   # => false
     def valid?
       errors.empty?
     end