From f97832b1e4406a76d268a96b521d2297adec0ae3 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Tue, 24 Mar 2009 12:15:43 +0000 Subject: Merge docrails --- activeresource/lib/active_resource/base.rb | 20 ++++++++++---------- activeresource/lib/active_resource/connection.rb | 22 +++++++++++----------- activeresource/lib/active_resource/validations.rb | 17 +++++++++-------- 3 files changed, 30 insertions(+), 29 deletions(-) (limited to 'activeresource/lib/active_resource') diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb index a8c0da31f2..6cb5beb789 100644 --- a/activeresource/lib/active_resource/base.rb +++ b/activeresource/lib/active_resource/base.rb @@ -19,7 +19,7 @@ module ActiveResource # end # # Now the Person class is mapped to RESTful resources located at http://api.people.com:3000/people/, and - # you can now use Active Resource's lifecycles methods to manipulate resources. In the case where you already have + # you can now use Active Resource's lifecycle methods to manipulate resources. In the case where you already have # an existing model with the same name as the desired RESTful resource you can set the +element_name+ value. # # class PersonResource < ActiveResource::Base @@ -112,6 +112,7 @@ module ActiveResource # # Note: Some values cannot be provided in the URL passed to site. e.g. email addresses # as usernames. In those situations you should use the separate user and password option. + # # == Errors & Validation # # Error handling and validation is handled in much the same manner as you're used to seeing in @@ -156,7 +157,7 @@ module ActiveResource # # === Validation errors # - # Active Resource supports validations on resources and will return errors if any these validations fail + # Active Resource supports validations on resources and will return errors if any of these validations fail # (e.g., "First name can not be blank" and so on). These types of errors are denoted in the response by # a response code of 422 and an XML representation of the validation errors. The save operation will # then fail (with a false return value) and the validation errors can be accessed on the resource in question. @@ -413,7 +414,7 @@ module ActiveResource # will split from the +prefix_options+. # # ==== Options - # * +prefix_options+ - A hash to add a prefix to the request for nested URL's (e.g., :account_id => 19 + # * +prefix_options+ - A hash to add a prefix to the request for nested URLs (e.g., :account_id => 19 # would yield a URL like /accounts/19/purchases.xml). # * +query_options+ - A hash to add items to the query string for the request. # @@ -691,7 +692,7 @@ module ActiveResource end - # A method to determine if the resource a \new object (i.e., it has not been POSTed to the remote service yet). + # Returns +true+ if this object hasn't yet been saved, otherwise, returns +false+. # # ==== Examples # not_new = Computer.create(:brand => 'Apple', :make => 'MacBook', :vendor => 'MacMall') @@ -760,7 +761,7 @@ module ActiveResource id.hash end - # Duplicate the current resource without saving it. + # Duplicates the current resource without saving it. # # ==== Examples # my_invoice = Invoice.create(:customer => 'That Company') @@ -779,8 +780,8 @@ module ActiveResource end end - # A method to \save (+POST+) or \update (+PUT+) a resource. It delegates to +create+ if a \new object, - # +update+ if it is existing. If the response to the \save includes a body, it will be assumed that this body + # Saves (+POST+) or \updates (+PUT+) a resource. Delegates to +create+ if the object is \new, + # +update+ if it exists. If the response to the \save includes a body, it will be assumed that this body # is XML for the final object as it looked after the \save (which would include attributes like +created_at+ # that weren't part of the original submit). # @@ -832,7 +833,7 @@ module ActiveResource !new? && self.class.exists?(to_param, :params => prefix_options) end - # A method to convert the the resource to an XML string. + # Converts the resource to an XML string representation. # # ==== Options # The +options+ parameter is handed off to the +to_xml+ method on each @@ -861,8 +862,7 @@ module ActiveResource attributes.to_xml({:root => self.class.element_name}.merge(options)) end - # Returns a JSON string representing the model. Some configuration is - # available through +options+. + # Converts the resource to a JSON string representation. # # ==== Options # The +options+ are passed to the +to_json+ method on each diff --git a/activeresource/lib/active_resource/connection.rb b/activeresource/lib/active_resource/connection.rb index 85103b53c5..80d5c95b68 100644 --- a/activeresource/lib/active_resource/connection.rb +++ b/activeresource/lib/active_resource/connection.rb @@ -95,46 +95,46 @@ module ActiveResource @password = URI.decode(@site.password) if @site.password end - # Set user for remote service. + # Sets the user for remote service. def user=(user) @user = user end - # Set password for remote service. + # Sets the password for remote service. def password=(password) @password = password end - # Set the number of seconds after which HTTP requests to the remote service should time out. + # Sets the number of seconds after which HTTP requests to the remote service should time out. def timeout=(timeout) @timeout = timeout end - # Execute a GET request. + # Executes a GET request. # Used to get (find) resources. def get(path, headers = {}) format.decode(request(:get, path, build_request_headers(headers, :get)).body) end - # Execute a DELETE request (see HTTP protocol documentation if unfamiliar). + # Executes a DELETE request (see HTTP protocol documentation if unfamiliar). # Used to delete resources. def delete(path, headers = {}) request(:delete, path, build_request_headers(headers, :delete)) end - # Execute a PUT request (see HTTP protocol documentation if unfamiliar). + # Executes a PUT request (see HTTP protocol documentation if unfamiliar). # Used to update resources. def put(path, body = '', headers = {}) request(:put, path, body.to_s, build_request_headers(headers, :put)) end - # Execute a POST request. + # Executes a POST request. # Used to create new resources. def post(path, body = '', headers = {}) request(:post, path, body.to_s, build_request_headers(headers, :post)) end - # Execute a HEAD request. + # Executes a HEAD request. # Used to obtain meta-information about resources, such as whether they exist and their size (via response headers). def head(path, headers = {}) request(:head, path, build_request_headers(headers)) @@ -142,7 +142,7 @@ module ActiveResource private - # Makes request to remote service. + # Makes a request to the remote service. def request(method, path, *arguments) logger.info "#{method.to_s.upcase} #{site.scheme}://#{site.host}:#{site.port}#{path}" if logger result = nil @@ -153,7 +153,7 @@ module ActiveResource raise TimeoutError.new(e.message) end - # Handles response and error codes from remote service. + # Handles response and error codes from the remote service. def handle_response(response) case response.code.to_i when 301,302 @@ -183,7 +183,7 @@ module ActiveResource end end - # Creates new Net::HTTP instance for communication with + # Creates new Net::HTTP instance for communication with the # remote service and resources. def http http = Net::HTTP.new(@site.host, @site.port) diff --git a/activeresource/lib/active_resource/validations.rb b/activeresource/lib/active_resource/validations.rb index de3339935f..8d21f8adbb 100644 --- a/activeresource/lib/active_resource/validations.rb +++ b/activeresource/lib/active_resource/validations.rb @@ -3,7 +3,7 @@ module ActiveResource end # Active Resource validation is reported to and from this object, which is used by Base#save - # to determine whether the object in a valid state to be saved. See usage example in Validations. + # to determine whether the object is in a valid state to be saved. See usage example in Validations. class Errors include Enumerable attr_reader :errors @@ -14,7 +14,10 @@ module ActiveResource @base, @errors = base, {} end - # Add an error to the base Active Resource object rather than an attribute. + # Adds an error to the base object instead of any particular attribute. This is used + # to report errors that don't tie to any specific attribute, but rather to the object + # as a whole. These error messages don't get prepended with any field name when iterating + # with +each_full+, so they should be complete sentences. # # ==== Examples # my_folder = Folder.find(1) @@ -68,9 +71,9 @@ module ActiveResource !@errors[attribute.to_s].nil? end - # 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+. + # 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+. # # ==== Examples # my_person = Person.new(params[:person]) @@ -92,9 +95,7 @@ module ActiveResource alias :[] :on - # 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+. + # Returns errors assigned to the base object through +add_to_base+ according to the normal rules of on(attribute). # # ==== Examples # my_account = Account.find(1) -- cgit v1.2.3