diff options
| author | Pratik Naik <pratiknaik@gmail.com> | 2008-05-25 12:29:00 +0100 |
|---|---|---|
| committer | Pratik Naik <pratiknaik@gmail.com> | 2008-05-25 12:29:00 +0100 |
| commit | 98dc582742779081e71e697fcdf8d9ae2b421b16 (patch) | |
| tree | f5680eef86e689a10d0f75434ba6a4e94829e439 | |
| parent | 6277fd91133a3566333612857510d74de60d67f4 (diff) | |
| download | rails-98dc582742779081e71e697fcdf8d9ae2b421b16.tar.gz rails-98dc582742779081e71e697fcdf8d9ae2b421b16.tar.bz2 rails-98dc582742779081e71e697fcdf8d9ae2b421b16.zip | |
Merge docrails.
Signed-off-by: Pratik Naik <pratiknaik@gmail.com>
85 files changed, 886 insertions, 778 deletions
diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index 7ed133d099..030bb178da 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -5,12 +5,12 @@ require 'action_mailer/utils' require 'tmail/net' module ActionMailer #:nodoc: - # ActionMailer allows you to send email from your application using a mailer model and views. + # Action Mailer allows you to send email from your application using a mailer model and views. # # # = Mailer Models # - # To use ActionMailer, you need to create a mailer model. + # To use Action Mailer, you need to create a mailer model. # # $ script/generate mailer Notifier # @@ -54,7 +54,7 @@ module ActionMailer #:nodoc: # # = Mailer views # - # Like ActionController, each mailer class has a corresponding view directory + # Like Action Controller, each mailer class has a corresponding view directory # in which each method of the class looks for a template with its name. # To define a template to be used with a mailing, create an <tt>.erb</tt> file with the same name as the method # in your mailer model. For example, in the mailer defined above, the template at @@ -157,7 +157,7 @@ module ActionMailer #:nodoc: # end # end # - # Multipart messages can also be used implicitly because ActionMailer will automatically + # Multipart messages can also be used implicitly because Action Mailer will automatically # detect and use multipart templates, where each template is named after the name of the action, followed # by the content type. Each such detected template will be added as separate part to the message. # @@ -383,8 +383,8 @@ module ActionMailer #:nodoc: # Receives a raw email, parses it into an email object, decodes it, # instantiates a new mailer, and passes the email object to the mailer - # object's #receive method. If you want your mailer to be able to - # process incoming messages, you'll need to implement a #receive + # object's +receive+ method. If you want your mailer to be able to + # process incoming messages, you'll need to implement a +receive+ # method that accepts the email object as a parameter: # # class MyMailer < ActionMailer::Base @@ -490,7 +490,7 @@ module ActionMailer #:nodoc: end # Delivers a TMail::Mail object. By default, it delivers the cached mail - # object (from the #create! method). If no cached mail object exists, and + # object (from the <tt>create!</tt> method). If no cached mail object exists, and # no alternate has been given as the parameter, this will fail. def deliver!(mail = @mail) raise "no mail object available for delivery!" unless mail diff --git a/actionmailer/lib/action_mailer/helpers.rb b/actionmailer/lib/action_mailer/helpers.rb index 3e5ed9e9d7..9c5fcc6afb 100644 --- a/actionmailer/lib/action_mailer/helpers.rb +++ b/actionmailer/lib/action_mailer/helpers.rb @@ -34,7 +34,7 @@ module ActionMailer # helper FooHelper # includes FooHelper in the template class. # helper { def foo() "#{bar} is the very best" end } - # evaluates the block in the template class, adding method #foo. + # evaluates the block in the template class, adding method +foo+. # helper(:three, BlindHelper) { def mice() 'mice' end } # does all three. def helper(*args, &block) diff --git a/actionmailer/lib/action_mailer/part.rb b/actionmailer/lib/action_mailer/part.rb index de1b1689f7..2dabf15f08 100644 --- a/actionmailer/lib/action_mailer/part.rb +++ b/actionmailer/lib/action_mailer/part.rb @@ -5,7 +5,7 @@ require 'action_mailer/utils' module ActionMailer # Represents a subpart of an email message. It shares many similar # attributes of ActionMailer::Base. Although you can create parts manually - # and add them to the #parts list of the mailer, it is easier + # and add them to the +parts+ list of the mailer, it is easier # to use the helper methods in ActionMailer::PartContainer. class Part include ActionMailer::AdvAttrAccessor @@ -13,7 +13,7 @@ module ActionMailer # Represents the body of the part, as a string. This should not be a # Hash (like ActionMailer::Base), but if you want a template to be rendered - # into the body of a subpart you can do it with the mailer's #render method + # into the body of a subpart you can do it with the mailer's +render+ method # and assign the result here. adv_attr_accessor :body diff --git a/actionpack/lib/action_controller/assertions/model_assertions.rb b/actionpack/lib/action_controller/assertions/model_assertions.rb index 0b4313055a..d25214bb66 100644 --- a/actionpack/lib/action_controller/assertions/model_assertions.rb +++ b/actionpack/lib/action_controller/assertions/model_assertions.rb @@ -1,7 +1,8 @@ module ActionController module Assertions module ModelAssertions - # Ensures that the passed record is valid by ActiveRecord standards and returns any error messages if it is not. + # Ensures that the passed record is valid by Active Record standards and + # returns any error messages if it is not. # # ==== Examples # diff --git a/actionpack/lib/action_controller/assertions/routing_assertions.rb b/actionpack/lib/action_controller/assertions/routing_assertions.rb index 2acd003243..491b72d586 100644 --- a/actionpack/lib/action_controller/assertions/routing_assertions.rb +++ b/actionpack/lib/action_controller/assertions/routing_assertions.rb @@ -59,7 +59,7 @@ module ActionController end end - # Asserts that the provided options can be used to generate the provided path. This is the inverse of #assert_recognizes. + # Asserts that the provided options can be used to generate the provided path. This is the inverse of +assert_recognizes+. # The +extras+ parameter is used to tell the request the names and values of additional request parameters that would be in # a query string. The +message+ parameter allows you to specify a custom error message for assertion failures. # @@ -96,8 +96,8 @@ module ActionController end # Asserts that path and options match both ways; in other words, it verifies that <tt>path</tt> generates - # <tt>options</tt> and then that <tt>options</tt> generates <tt>path</tt>. This essentially combines #assert_recognizes - # and #assert_generates into one step. + # <tt>options</tt> and then that <tt>options</tt> generates <tt>path</tt>. This essentially combines +assert_recognizes+ + # and +assert_generates+ into one step. # # The +extras+ hash allows you to specify options that would normally be provided as a query string to the action. The # +message+ parameter allows you to specify a custom error message to display upon failure. diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb index 9ef093acfc..d3594e711c 100644 --- a/actionpack/lib/action_controller/assertions/selector_assertions.rb +++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb @@ -12,12 +12,12 @@ module ActionController NO_STRIP = %w{pre script style textarea} end - # Adds the #assert_select method for use in Rails functional + # Adds the +assert_select+ method for use in Rails functional # test cases, which can be used to make assertions on the response HTML of a controller - # action. You can also call #assert_select within another #assert_select to + # action. You can also call +assert_select+ within another +assert_select+ to # make assertions on elements selected by the enclosing assertion. # - # Use #css_select to select elements without making an assertions, either + # Use +css_select+ to select elements without making an assertions, either # from the response HTML or elements selected by the enclosing assertion. # # In addition to HTML responses, you can make the following assertions: @@ -44,8 +44,8 @@ module ActionController # base element and any of its children. Returns an empty array if no # match is found. # - # The selector may be a CSS selector expression (+String+), an expression - # with substitution values (+Array+) or an HTML::Selector object. + # The selector may be a CSS selector expression (String), an expression + # with substitution values (Array) or an HTML::Selector object. # # ==== Examples # # Selects all div tags @@ -114,8 +114,8 @@ module ActionController # starting from (and including) that element and all its children in # depth-first order. # - # If no element if specified, calling #assert_select will select from the - # response HTML. Calling #assert_select inside an #assert_select block will + # If no element if specified, calling +assert_select+ will select from the + # response HTML. Calling #assert_select inside an +assert_select+ block will # run the assertion for each element selected by the enclosing assertion. # # ==== Example @@ -130,7 +130,7 @@ module ActionController # assert_select "li" # end # - # The selector may be a CSS selector expression (+String+), an expression + # The selector may be a CSS selector expression (String), an expression # with substitution values, or an HTML::Selector object. # # === Equality Tests @@ -356,16 +356,16 @@ module ActionController # # === Using blocks # - # Without a block, #assert_select_rjs merely asserts that the response + # Without a block, +assert_select_rjs+ merely asserts that the response # contains one or more RJS statements that replace or update content. # - # With a block, #assert_select_rjs also selects all elements used in + # With a block, +assert_select_rjs+ also selects all elements used in # these statements and passes them to the block. Nested assertions are # supported. # - # Calling #assert_select_rjs with no arguments and using nested asserts + # Calling +assert_select_rjs+ with no arguments and using nested asserts # asserts that the HTML content is returned by one or more RJS statements. - # Using #assert_select directly makes the same assertion on the content, + # Using +assert_select+ directly makes the same assertion on the content, # but without distinguishing whether the content is returned in an HTML # or JavaScript. # @@ -601,7 +601,7 @@ module ActionController RJS_PATTERN_UNICODE_ESCAPED_CHAR = /\\u([0-9a-zA-Z]{4})/ end - # #assert_select and #css_select call this to obtain the content in the HTML + # +assert_select+ and +css_select+ call this to obtain the content in the HTML # page, or from all the RJS statements, depending on the type of response. def response_from_page_or_rjs() content_type = @response.content_type diff --git a/actionpack/lib/action_controller/assertions/tag_assertions.rb b/actionpack/lib/action_controller/assertions/tag_assertions.rb index 4ac489520a..90ba3668fb 100644 --- a/actionpack/lib/action_controller/assertions/tag_assertions.rb +++ b/actionpack/lib/action_controller/assertions/tag_assertions.rb @@ -91,7 +91,7 @@ module ActionController # :descendant => { :tag => "span", # :child => /hello world/ } # - # <b>Please note</b>: #assert_tag and #assert_no_tag only work + # <b>Please note</b>: +assert_tag+ and +assert_no_tag+ only work # with well-formed XHTML. They recognize a few tags as implicitly self-closing # (like br and hr and such) but will not work correctly with tags # that allow optional closing tags (p, li, td). <em>You must explicitly @@ -104,8 +104,8 @@ module ActionController end end - # Identical to #assert_tag, but asserts that a matching tag does _not_ - # exist. (See #assert_tag for a full discussion of the syntax.) + # Identical to +assert_tag+, but asserts that a matching tag does _not_ + # exist. (See +assert_tag+ for a full discussion of the syntax.) # # === Examples # # Assert that there is not a "div" containing a "p" diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb index ea55fe42ce..a036600c2b 100755 --- a/actionpack/lib/action_controller/base.rb +++ b/actionpack/lib/action_controller/base.rb @@ -104,7 +104,7 @@ module ActionController #:nodoc: # end # # Actions, by default, render a template in the <tt>app/views</tt> directory corresponding to the name of the controller and action - # after executing code in the action. For example, the +index+ action of the +GuestBookController+ would render the + # after executing code in the action. For example, the +index+ action of the GuestBookController would render the # template <tt>app/views/guestbook/index.erb</tt> by default after populating the <tt>@entries</tt> instance variable. # # Unlike index, the sign action will not render a template. After performing its main purpose (creating a @@ -118,10 +118,10 @@ module ActionController #:nodoc: # # Requests are processed by the Action Controller framework by extracting the value of the "action" key in the request parameters. # This value should hold the name of the action to be performed. Once the action has been identified, the remaining - # request parameters, the session (if one is available), and the full request with all the http headers are made available to + # request parameters, the session (if one is available), and the full request with all the HTTP headers are made available to # the action through instance variables. Then the action is performed. # - # The full request object is available with the request accessor and is primarily used to query for http headers. These queries + # The full request object is available with the request accessor and is primarily used to query for HTTP headers. These queries # are made by accessing the environment hash, like this: # # def server_ip @@ -291,10 +291,10 @@ module ActionController #:nodoc: cattr_accessor :allow_concurrency # Modern REST web services often need to submit complex data to the web application. - # The param_parsers hash lets you register handlers which will process the http body and add parameters to the - # <tt>params</tt> hash. These handlers are invoked for post and put requests. + # The <tt>@@param_parsers</tt> hash lets you register handlers which will process the HTTP body and add parameters to the + # <tt>params</tt> hash. These handlers are invoked for POST and PUT requests. # - # By default application/xml is enabled. A XmlSimple class with the same param name as the root will be instantiated + # By default <tt>application/xml</tt> is enabled. A XmlSimple class with the same param name as the root will be instantiated # in the <tt>params</tt>. This allows XML requests to mask themselves as regular form submissions, so you can have one # action serve both regular forms and web service requests. # @@ -307,7 +307,7 @@ module ActionController #:nodoc: # # Note: Up until release 1.1 of Rails, Action Controller would default to using XmlSimple configured to discard the # root node for such requests. The new default is to keep the root, such that "<r><name>David</name></r>" results - # in params[:r][:name] for "David" instead of params[:name]. To get the old behavior, you can + # in <tt>params[:r][:name]</tt> for "David" instead of <tt>params[:name]</tt>. To get the old behavior, you can # re-register XmlSimple as application/xml handler ike this: # # ActionController::Base.param_parsers[Mime::XML] = diff --git a/actionpack/lib/action_controller/cgi_ext/cookie.rb b/actionpack/lib/action_controller/cgi_ext/cookie.rb index a244e2a39a..ef033fb4f3 100644 --- a/actionpack/lib/action_controller/cgi_ext/cookie.rb +++ b/actionpack/lib/action_controller/cgi_ext/cookie.rb @@ -6,25 +6,24 @@ class CGI #:nodoc: attr_accessor :name, :value, :path, :domain, :expires attr_reader :secure, :http_only - # Create a new CGI::Cookie object. + # Creates a new CGI::Cookie object. # # The contents of the cookie can be specified as a +name+ and one # or more +value+ arguments. Alternatively, the contents can # be specified as a single hash argument. The possible keywords of # this hash are as follows: # - # name:: the name of the cookie. Required. - # value:: the cookie's value or list of values. - # path:: the path for which this cookie applies. Defaults to the - # base directory of the CGI script. - # domain:: the domain for which this cookie applies. - # expires:: the time at which this cookie expires, as a +Time+ object. - # secure:: whether this cookie is a secure cookie or not (default to - # false). Secure cookies are only transmitted to HTTPS - # servers. - # http_only:: whether this cookie can be accessed by client side scripts (e.g. document.cookie) or only over HTTP - # More details: http://msdn2.microsoft.com/en-us/library/system.web.httpcookie.httponly.aspx - # Defaults to false. + # * <tt>:name</tt> - The name of the cookie. Required. + # * <tt>:value</tt> - The cookie's value or list of values. + # * <tt>:path</tt> - The path for which this cookie applies. Defaults to the + # base directory of the CGI script. + # * <tt>:domain</tt> - The domain for which this cookie applies. + # * <tt>:expires</tt> - The time at which this cookie expires, as a Time object. + # * <tt>:secure</tt> - Whether this cookie is a secure cookie or not (defaults to + # +false+). Secure cookies are only transmitted to HTTPS servers. + # * <tt>:http_only</tt> - Whether this cookie can be accessed by client side scripts (e.g. document.cookie) or only over HTTP. + # More details in http://msdn2.microsoft.com/en-us/library/system.web.httpcookie.httponly.aspx. Defaults to +false+. + # # These keywords correspond to attributes of the cookie object. def initialize(name = '', *value) if name.kind_of?(String) @@ -56,17 +55,17 @@ class CGI #:nodoc: super(@value) end - # Set whether the Cookie is a secure cookie or not. + # Sets whether the Cookie is a secure cookie or not. def secure=(val) @secure = val == true end - # Set whether the Cookie is an HTTP only cookie or not. + # Sets whether the Cookie is an HTTP only cookie or not. def http_only=(val) @http_only = val == true end - # Convert the Cookie to its string representation. + # Converts the Cookie to its string representation. def to_s buf = '' buf << @name << '=' @@ -79,11 +78,11 @@ class CGI #:nodoc: buf end - # Parse a raw cookie string into a hash of cookie-name=>Cookie + # Parses a raw cookie string into a hash of <tt>cookie-name => cookie-object</tt> # pairs. # # cookies = CGI::Cookie::parse("raw_cookie_string") - # # { "name1" => cookie1, "name2" => cookie2, ... } + # # => { "name1" => cookie1, "name2" => cookie2, ... } # def self.parse(raw_cookie) cookies = Hash.new([]) diff --git a/actionpack/lib/action_controller/cgi_process.rb b/actionpack/lib/action_controller/cgi_process.rb index 7e58c98bf2..8bc5e4c3a7 100644 --- a/actionpack/lib/action_controller/cgi_process.rb +++ b/actionpack/lib/action_controller/cgi_process.rb @@ -15,7 +15,7 @@ module ActionController #:nodoc: # * <tt>:new_session</tt> - if true, force creation of a new session. If not set, a new session is only created if none currently # exists. If false, a new session is never created, and if none currently exists and the +session_id+ option is not set, # an ArgumentError is raised. - # * <tt>:session_expires</tt> - the time the current session expires, as a +Time+ object. If not set, the session will continue + # * <tt>:session_expires</tt> - the time the current session expires, as a Time object. If not set, the session will continue # indefinitely. # * <tt>:session_domain</tt> - the hostname domain for which this session is valid. If not set, defaults to the hostname of the # server. diff --git a/actionpack/lib/action_controller/filters.rb b/actionpack/lib/action_controller/filters.rb index 6d0c83eb40..60d92d9b98 100644 --- a/actionpack/lib/action_controller/filters.rb +++ b/actionpack/lib/action_controller/filters.rb @@ -100,10 +100,10 @@ module ActionController #:nodoc: # # Around filters wrap an action, executing code both before and after. # They may be declared as method references, blocks, or objects responding - # to #filter or to both #before and #after. + # to +filter+ or to both +before+ and +after+. # - # To use a method as an around_filter, pass a symbol naming the Ruby method. - # Yield (or block.call) within the method to run the action. + # To use a method as an +around_filter+, pass a symbol naming the Ruby method. + # Yield (or <tt>block.call</tt>) within the method to run the action. # # around_filter :catch_exceptions # @@ -115,9 +115,9 @@ module ActionController #:nodoc: # raise # end # - # To use a block as an around_filter, pass a block taking as args both + # To use a block as an +around_filter+, pass a block taking as args both # the controller and the action block. You can't call yield directly from - # an around_filter block; explicitly call the action block instead: + # an +around_filter+ block; explicitly call the action block instead: # # around_filter do |controller, action| # logger.debug "before #{controller.action_name}" @@ -125,7 +125,7 @@ module ActionController #:nodoc: # logger.debug "after #{controller.action_name}" # end # - # To use a filter object with around_filter, pass an object responding + # To use a filter object with +around_filter+, pass an object responding # to <tt>:filter</tt> or both <tt>:before</tt> and <tt>:after</tt>. With a # filter method, yield to the block as above: # @@ -137,7 +137,7 @@ module ActionController #:nodoc: # end # end # - # With before and after methods: + # With +before+ and +after+ methods: # # around_filter Authorizer.new # @@ -154,9 +154,9 @@ module ActionController #:nodoc: # end # end # - # If the filter has before and after methods, the before method will be - # called before the action. If before renders or redirects, the filter chain is - # halted and after will not be run. See Filter Chain Halting below for + # If the filter has +before+ and +after+ methods, the +before+ method will be + # called before the action. If +before+ renders or redirects, the filter chain is + # halted and +after+ will not be run. See Filter Chain Halting below for # an example. # # == Filter chain skipping @@ -215,7 +215,7 @@ module ActionController #:nodoc: # # <tt>before_filter</tt> and <tt>around_filter</tt> may halt the request # before a controller action is run. This is useful, for example, to deny - # access to unauthenticated users or to redirect from http to https. + # access to unauthenticated users or to redirect from HTTP to HTTPS. # Simply call render or redirect. After filters will not be executed if the filter # chain is halted. # @@ -241,10 +241,10 @@ module ActionController #:nodoc: # . / # #after (actual filter code is run, unless the around filter does not yield) # - # If #around returns before yielding, #after will still not be run. The #before - # filter and controller action will not be run. If #before renders or redirects, - # the second half of #around and will still run but #after and the - # action will not. If #around fails to yield, #after will not be run. + # If +around+ returns before yielding, +after+ will still not be run. The +before+ + # filter and controller action will not be run. If +before+ renders or redirects, + # the second half of +around+ and will still run but +after+ and the + # action will not. If +around+ fails to yield, +after+ will not be run. class FilterChain < ActiveSupport::Callbacks::CallbackChain #:nodoc: def append_filter_to_chain(filters, filter_type, &block) @@ -471,7 +471,7 @@ module ActionController #:nodoc: # Shorthand for append_after_filter since it's the most common. alias :after_filter :append_after_filter - # If you append_around_filter A.new, B.new, the filter chain looks like + # If you <tt>append_around_filter A.new, B.new</tt>, the filter chain looks like # # B#before # A#before @@ -479,13 +479,13 @@ module ActionController #:nodoc: # A#after # B#after # - # With around filters which yield to the action block, #before and #after + # With around filters which yield to the action block, +before+ and +after+ # are the code before and after the yield. def append_around_filter(*filters, &block) filter_chain.append_filter_to_chain(filters, :around, &block) end - # If you prepend_around_filter A.new, B.new, the filter chain looks like: + # If you <tt>prepend_around_filter A.new, B.new</tt>, the filter chain looks like: # # A#before # B#before @@ -493,13 +493,13 @@ module ActionController #:nodoc: # B#after # A#after # - # With around filters which yield to the action block, #before and #after + # With around filters which yield to the action block, +before+ and +after+ # are the code before and after the yield. def prepend_around_filter(*filters, &block) filter_chain.prepend_filter_to_chain(filters, :around, &block) end - # Shorthand for append_around_filter since it's the most common. + # Shorthand for +append_around_filter+ since it's the most common. alias :around_filter :append_around_filter # Removes the specified filters from the +before+ filter chain. Note that this only works for skipping method-reference diff --git a/actionpack/lib/action_controller/helpers.rb b/actionpack/lib/action_controller/helpers.rb index a8bead4d34..ce5e8be54c 100644 --- a/actionpack/lib/action_controller/helpers.rb +++ b/actionpack/lib/action_controller/helpers.rb @@ -20,7 +20,7 @@ module ActionController #:nodoc: end # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+, - # +numbers+ and +ActiveRecord+ objects, to name a few. These helpers are available to all templates + # +numbers+ and Active Record objects, to name a few. These helpers are available to all templates # by default. # # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to @@ -32,7 +32,7 @@ module ActionController #:nodoc: # controller which inherits from it. # # ==== Examples - # The +to_s+ method from the +Time+ class can be wrapped in a helper method to display a custom message if + # The +to_s+ method from the Time class can be wrapped in a helper method to display a custom message if # the Time object is blank: # # module FormattedTimeHelper @@ -41,7 +41,7 @@ module ActionController #:nodoc: # end # end # - # +FormattedTimeHelper+ can now be included in a controller, using the +helper+ class method: + # FormattedTimeHelper can now be included in a controller, using the +helper+ class method: # # class EventsController < ActionController::Base # helper FormattedTimeHelper @@ -74,22 +74,22 @@ module ActionController #:nodoc: # The +helper+ class method can take a series of helper module names, a block, or both. # - # * <tt>*args</tt>: One or more +Modules+, +Strings+ or +Symbols+, or the special symbol <tt>:all</tt>. + # * <tt>*args</tt>: One or more modules, strings or symbols, or the special symbol <tt>:all</tt>. # * <tt>&block</tt>: A block defining helper methods. # # ==== Examples - # When the argument is a +String+ or +Symbol+, the method will provide the "_helper" suffix, require the file + # When the argument is a string or symbol, the method will provide the "_helper" suffix, require the file # and include the module in the template class. The second form illustrates how to include custom helpers # when working with namespaced controllers, or other cases where the file containing the helper definition is not # in one of Rails' standard load paths: # helper :foo # => requires 'foo_helper' and includes FooHelper # helper 'resources/foo' # => requires 'resources/foo_helper' and includes Resources::FooHelper # - # When the argument is a +Module+, it will be included directly in the template class. + # When the argument is a module it will be included directly in the template class. # helper FooHelper # => includes FooHelper # # When the argument is the symbol <tt>:all</tt>, the controller will include all helpers from - # <tt>app/helpers/**/*.rb</tt> under +RAILS_ROOT+. + # <tt>app/helpers/**/*.rb</tt> under RAILS_ROOT. # helper :all # # Additionally, the +helper+ class method can receive and evaluate a block, making the methods defined available diff --git a/actionpack/lib/action_controller/integration.rb b/actionpack/lib/action_controller/integration.rb index f0fc1945a9..bd69d02ed7 100644 --- a/actionpack/lib/action_controller/integration.rb +++ b/actionpack/lib/action_controller/integration.rb @@ -58,7 +58,7 @@ module ActionController class MultiPartNeededException < Exception end - # Create and initialize a new +Session+ instance. + # Create and initialize a new Session instance. def initialize reset! end @@ -136,25 +136,25 @@ module ActionController end # Performs a GET request, following any subsequent redirect. - # See #request_via_redirect() for more information. + # See +request_via_redirect+ for more information. def get_via_redirect(path, parameters = nil, headers = nil) request_via_redirect(:get, path, parameters, headers) end # Performs a POST request, following any subsequent redirect. - # See #request_via_redirect() for more information. + # See +request_via_redirect+ for more information. def post_via_redirect(path, parameters = nil, headers = nil) request_via_redirect(:post, path, parameters, headers) end # Performs a PUT request, following any subsequent redirect. - # See #request_via_redirect() for more information. + # See +request_via_redirect+ for more information. def put_via_redirect(path, parameters = nil, headers = nil) request_via_redirect(:put, path, parameters, headers) end # Performs a DELETE request, following any subsequent redirect. - # See #request_via_redirect() for more information. + # See +request_via_redirect+ for more information. def delete_via_redirect(path, parameters = nil, headers = nil) request_via_redirect(:delete, path, parameters, headers) end @@ -166,12 +166,12 @@ module ActionController # Performs a GET request with the given parameters. The parameters may # be +nil+, a Hash, or a string that is appropriately encoded - # (application/x-www-form-urlencoded or multipart/form-data). The headers - # should be a hash. The keys will automatically be upcased, with the + # (<tt>application/x-www-form-urlencoded</tt> or <tt>multipart/form-data</tt>). + # The headers should be a hash. The keys will automatically be upcased, with the # prefix 'HTTP_' added if needed. # - # You can also perform POST, PUT, DELETE, and HEAD requests with #post, - # #put, #delete, and #head. + # You can also perform POST, PUT, DELETE, and HEAD requests with +post+, + # +put+, +delete+, and +head+. def get(path, parameters = nil, headers = nil) process :get, path, parameters, headers end diff --git a/actionpack/lib/action_controller/mime_type.rb b/actionpack/lib/action_controller/mime_type.rb index f43e2ba06d..fa123f7808 100644 --- a/actionpack/lib/action_controller/mime_type.rb +++ b/actionpack/lib/action_controller/mime_type.rb @@ -104,7 +104,7 @@ module Mime list[text_xml].name = Mime::XML.to_s end - # Look for more specific xml-based types and sort them ahead of app/xml + # Look for more specific XML-based types and sort them ahead of app/xml if app_xml idx = app_xml @@ -158,7 +158,7 @@ module Mime end end - # Returns true if ActionPack should check requests using this Mime Type for possible request forgery. See + # Returns true if Action Pack should check requests using this Mime Type for possible request forgery. See # ActionController::RequestForgerProtection. def verify_request? !@@unverifiable_types.include?(to_sym) diff --git a/actionpack/lib/action_controller/polymorphic_routes.rb b/actionpack/lib/action_controller/polymorphic_routes.rb index e2b7716aa2..509fa6a08e 100644 --- a/actionpack/lib/action_controller/polymorphic_routes.rb +++ b/actionpack/lib/action_controller/polymorphic_routes.rb @@ -1,6 +1,6 @@ module ActionController # Polymorphic URL helpers are methods for smart resolution to a named route call when - # given an ActiveRecord model instance. They are to be used in combination with + # given an Active Record model instance. They are to be used in combination with # ActionController::Resources. # # These methods are useful when you want to generate correct URL or path to a RESTful @@ -9,7 +9,9 @@ module ActionController # Nested resources and/or namespaces are also supported, as illustrated in the example: # # polymorphic_url([:admin, @article, @comment]) - # #-> results in: + # + # results in: + # # admin_article_comment_url(@article, @comment) # # == Usage within the framework @@ -38,11 +40,8 @@ module ActionController # # Example usage: # - # edit_polymorphic_path(@post) - # #=> /posts/1/edit - # - # formatted_polymorphic_path([@post, :pdf]) - # #=> /posts/1.pdf + # edit_polymorphic_path(@post) # => "/posts/1/edit" + # formatted_polymorphic_path([@post, :pdf]) # => "/posts/1.pdf" module PolymorphicRoutes # Constructs a call to a named RESTful route for the given record and returns the # resulting URL string. For example: diff --git a/actionpack/lib/action_controller/resources.rb b/actionpack/lib/action_controller/resources.rb index 26f75780c1..9fb1f9fa39 100644 --- a/actionpack/lib/action_controller/resources.rb +++ b/actionpack/lib/action_controller/resources.rb @@ -191,7 +191,7 @@ module ActionController # end # end # - # Along with the routes themselves, #resources generates named routes for use in + # Along with the routes themselves, +resources+ generates named routes for use in # controllers and views. <tt>map.resources :messages</tt> produces the following named routes and helpers: # # Named Route Helpers @@ -208,7 +208,7 @@ module ActionController # edit_message edit_message_url(id), hash_for_edit_message_url(id), # edit_message_path(id), hash_for_edit_message_path(id) # - # You can use these helpers instead of #url_for or methods that take #url_for parameters. For example: + # You can use these helpers instead of +url_for+ or methods that take +url_for+ parameters. For example: # # redirect_to :controller => 'messages', :action => 'index' # # and @@ -406,7 +406,7 @@ module ActionController # end # end # - # Along with the routes themselves, #resource generates named routes for + # Along with the routes themselves, +resource+ generates named routes for # use in controllers and views. <tt>map.resource :account</tt> produces # these named routes and helpers: # diff --git a/actionpack/lib/action_controller/routing/builder.rb b/actionpack/lib/action_controller/routing/builder.rb index b1a98d1a51..4740113ed0 100644 --- a/actionpack/lib/action_controller/routing/builder.rb +++ b/actionpack/lib/action_controller/routing/builder.rb @@ -23,9 +23,9 @@ module ActionController # Accepts a "route path" (a string defining a route), and returns the array # of segments that corresponds to it. Note that the segment array is only # partially initialized--the defaults and requirements, for instance, need - # to be set separately, via the #assign_route_options method, and the - # #optional? method for each segment will not be reliable until after - # #assign_route_options is called, as well. + # to be set separately, via the +assign_route_options+ method, and the + # <tt>optional?</tt> method for each segment will not be reliable until after + # +assign_route_options+ is called, as well. def segments_for_route_path(path) rest, segments = path, [] diff --git a/actionpack/lib/action_controller/session/cookie_store.rb b/actionpack/lib/action_controller/session/cookie_store.rb index ada1862c3e..b477c1f7da 100644 --- a/actionpack/lib/action_controller/session/cookie_store.rb +++ b/actionpack/lib/action_controller/session/cookie_store.rb @@ -34,7 +34,7 @@ require 'openssl' # to generate the HMAC message digest # such as 'MD5', 'RIPEMD160', 'SHA256', etc. # # To generate a secret key for an existing application, run -# `rake secret` and set the key in config/environment.rb. +# "rake secret" and set the key in config/environment.rb. # # Note that changing digest or secret invalidates all existing sessions! class CGI::Session::CookieStore diff --git a/actionpack/lib/action_controller/test_process.rb b/actionpack/lib/action_controller/test_process.rb index f03ed5b2a7..0cf143210d 100644 --- a/actionpack/lib/action_controller/test_process.rb +++ b/actionpack/lib/action_controller/test_process.rb @@ -3,7 +3,7 @@ require 'action_controller/test_case' module ActionController #:nodoc: class Base - # Process a test request called with a +TestRequest+ object. + # Process a test request called with a TestRequest object. def self.process_test(request) new.process_test(request) end @@ -358,7 +358,7 @@ module ActionController #:nodoc: module TestProcess def self.included(base) - # execute the request simulating a specific http method and set/volley the response + # execute the request simulating a specific HTTP method and set/volley the response %w( get post put delete head ).each do |method| base.class_eval <<-EOV, __FILE__, __LINE__ def #{method}(action, parameters = nil, session = nil, flash = nil) diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb index dfc7e2b3ed..e5a95a961c 100644 --- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb @@ -11,8 +11,8 @@ module ActionView # === Using asset hosts # By default, Rails links to these assets on the current host in the public # folder, but you can direct Rails to link to assets from a dedicated assets server by - # setting ActionController::Base.asset_host in your environment.rb. For example, - # let's say your asset host is assets.example.com. + # setting ActionController::Base.asset_host in your <tt>config/environment.rb</tt>. For example, + # let's say your asset host is <tt>assets.example.com</tt>. # # ActionController::Base.asset_host = "assets.example.com" # image_tag("rails.png") @@ -22,8 +22,8 @@ module ActionView # # This is useful since browsers typically open at most two connections to a single host, # which means your assets often wait in single file for their turn to load. You can - # alleviate this by using a %d wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com") - # to automatically distribute asset requests among four hosts (e.g., assets0.example.com through assets3.example.com) + # alleviate this by using a <tt>%d</tt> wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com") + # to automatically distribute asset requests among four hosts (e.g., "assets0.example.com" through "assets3.example.com") # so browsers will open eight connections rather than two. # # image_tag("rails.png") @@ -293,9 +293,9 @@ module ActionView end # Computes the path to a stylesheet asset in the public stylesheets directory. - # If the +source+ filename has no extension, .css will be appended. + # If the +source+ filename has no extension, <tt>.css</tt> will be appended. # Full paths from the document root will be passed through. - # Used internally by stylesheet_link_tag to build the stylesheet path. + # Used internally by +stylesheet_link_tag+ to build the stylesheet path. # # ==== Examples # stylesheet_path "style" # => /stylesheets/style.css @@ -309,7 +309,7 @@ module ActionView alias_method :path_to_stylesheet, :stylesheet_path # aliased to avoid conflicts with a stylesheet_path named route # Returns a stylesheet link tag for the sources specified as arguments. If - # you don't specify an extension, .css will be appended automatically. + # you don't specify an extension, <tt>.css</tt> will be appended automatically. # You can modify the link attributes by passing a hash as the last argument. # # ==== Examples @@ -379,7 +379,7 @@ module ActionView # Computes the path to an image asset in the public images directory. # Full paths from the document root will be passed through. - # Used internally by image_tag to build the image path. + # Used internally by +image_tag+ to build the image path. # # ==== Examples # image_path("edit") # => /images/edit @@ -454,8 +454,8 @@ module ActionView end end - # Add the .ext if not present. Return full URLs otherwise untouched. - # Prefix with /dir/ if lacking a leading /. Account for relative URL + # Add the the extension +ext+ if not present. Return full URLs otherwise untouched. + # Prefix with <tt>/dir/</tt> if lacking a leading +/+. Account for relative URL # roots. Rewrite the asset path for cache-busting asset ids. Include # asset host, if configured, with the correct request protocol. def compute_public_path(source, dir, ext = nil, include_host = true) @@ -502,9 +502,9 @@ module ActionView end end - # Pick an asset host for this source. Returns nil if no host is set, + # Pick an asset host for this source. Returns +nil+ if no host is set, # the host if no wildcard is set, the host interpolated with the - # numbers 0-3 if it contains %d (the number is the source hash mod 4), + # numbers 0-3 if it contains <tt>%d</tt> (the number is the source hash mod 4), # or the value returned from invoking the proc if it's a proc. def compute_asset_host(source) if host = ActionController::Base.asset_host diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 0962be2c79..0791feb9ac 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -86,15 +86,15 @@ module ActionView # <%= f.text_field :author %><br /> # <% end %> # - # There, +form_for+ is able to generate the rest of RESTful parameters + # There, +form_for+ is able to generate the rest of RESTful form parameters # based on introspection on the record, but to understand what it does we # need to dig first into the alternative generic usage it is based upon. # # === Generic form_for # - # The generic way to call +form_for+ requires a few arguments: + # The generic way to call +form_for+ yields a form builder around a model: # - # <% form_for :person, @person, :url => { :action => "update" } do |f| %> + # <% form_for :person, :url => { :action => "update" } do |f| %> # <%= f.error_messages %> # First name: <%= f.text_field :first_name %><br /> # Last name : <%= f.text_field :last_name %><br /> @@ -102,21 +102,48 @@ module ActionView # Admin? : <%= f.check_box :admin %><br /> # <% end %> # + # There, the first argument is a symbol or string with the name of the + # object the form is about, and also the name of the instance variable the + # object is stored in. + # + # The form builder acts as a regular form helper that somehow carries the + # model. Thus, the idea is that + # + # <%= f.text_field :first_name %> + # + # gets expanded to + # + # <%= text_field :person, :first_name %> + # + # If the instance variable is not <tt>@person</tt> you can pass the actual + # record as the second argument: + # + # <% form_for :person, person, :url => { :action => "update" } do |f| %> + # ... + # <% end %> + # + # In that case you can think + # + # <%= f.text_field :first_name %> + # + # gets expanded to + # + # <%= text_field :person, :first_name, :object => person %> + # + # You can even display error messages of the wrapped model this way: + # + # <%= f.error_messages %> + # + # In any of its variants, the rightmost argument to +form_for+ is an + # optional hash of options: + # + # * <tt>:url</tt> - The URL the form is submitted to. It takes the same fields + # you pass to +url_for+ or +link_to+. In particular you may pass here a + # named route directly as well. Defaults to the current action. + # * <tt>:html</tt> - Optional HTML attributes for the form tag. + # # Worth noting is that the +form_for+ tag is called in a ERb evaluation block, - # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>. Also - # worth noting is that +form_for+ yields a form builder object, in this - # example as +f+, which emulates the API for the stand-alone FormHelper - # methods, but without the object name. So instead of <tt>text_field :person, :name</tt>, - # you get away with <tt>f.text_field :name</tt>. Notice that you can even do - # <tt><%= f.error_messages %></tt> to display the error messsages of the model - # object in question. - # - # Even further, the +form_for+ method allows you to more easily escape the - # instance variable convention. So while the stand-alone approach would require - # <tt>text_field :person, :name, :object => person</tt> to work with local - # variables instead of instance ones, the +form_for+ calls remain the same. - # You simply declare once with <tt>:person, person</tt> and all subsequent - # field calls save <tt>:person</tt> and <tt>:object => person</tt>. + # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>. # # Also note that +form_for+ doesn't create an exclusive scope. It's still # possible to use both the stand-alone FormHelper methods and methods from @@ -133,40 +160,32 @@ module ActionView # designed to work with an object as base, like FormOptionHelper#collection_select # and DateHelper#datetime_select. # - # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>. - # For example: - # - # <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %> - # ... - # <% end %> - # - # The above form will then have the +id+ attribute with the value "person_form", - # which you can then style with CSS or manipulate with JavaScript. - # - # === Relying on record identification + # === Resource-oriented style # # As we said above, in addition to manually configuring the +form_for+ call, - # you can rely on record identification, which will use the conventions and - # named routes of that approach. This is the preferred way to use +form_for+ - # nowadays: + # you can rely on automated resource identification, which will use the conventions + # and named routes of that approach. This is the preferred way to use +form_for+ + # nowadays. + # + # For example, if <tt>@post</tt> is an existing record you want to edit # - # <% form_for(@post) do |f| %> + # <% form_for @post do |f| %> # ... # <% end %> # - # This will expand to be the same as: + # is equivalent to something like: # # <% form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %> # ... # <% end %> # - # And for new records: + # And for new records # # <% form_for(Post.new) do |f| %> # ... # <% end %> # - # This will expand to be the same as: + # expands to # # <% form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %> # ... @@ -305,13 +324,13 @@ module ActionView # # ==== Examples # label(:post, :title) - # #=> <label for="post_title">Title</label> + # # => <label for="post_title">Title</label> # # label(:post, :title, "A short title") - # #=> <label for="post_title">A short title</label> + # # => <label for="post_title">A short title</label> # # label(:post, :title, "A short title", :class => "title_label") - # #=> <label for="post_title" class="title_label">A short title</label> + # # => <label for="post_title" class="title_label">A short title</label> # def label(object_name, method, text = nil, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_label_tag(text, options) diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb index 6f3818659e..e0a097e367 100644 --- a/actionpack/lib/action_view/helpers/form_options_helper.rb +++ b/actionpack/lib/action_view/helpers/form_options_helper.rb @@ -119,7 +119,7 @@ module ActionView # end # end # - # Sample usage (selecting the associated +Author+ for an instance of +Post+, <tt>@post</tt>): + # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>): # collection_select(:post, :author_id, Author.find(:all), :id, :name_with_initial, {:prompt => true}) # # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return: @@ -144,7 +144,7 @@ module ActionView # In addition to the <tt>:include_blank</tt> option documented above, # this method also supports a <tt>:model</tt> option, which defaults # to TimeZone. This may be used by users to specify a different time - # zone model object. (See #time_zone_options_for_select for more + # zone model object. (See +time_zone_options_for_select+ for more # information.) # # You can also supply an array of TimeZone objects @@ -153,7 +153,7 @@ module ActionView # obtaining a list of the US time zones.) # # Finally, this method supports a <tt>:default</tt> option, which selects - # a default TimeZone if the object's time zone is nil. + # a default TimeZone if the object's time zone is +nil+. # # Examples: # time_zone_select( "user", "time_zone", nil, :include_blank => true) @@ -172,7 +172,7 @@ module ActionView # Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. Given a container # where the elements respond to first and last (such as a two-element array), the "lasts" serve as option values and # the "firsts" as option text. Hashes are turned into this form automatically, so the keys become "firsts" and values - # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag. +Selected+ + # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag. +selected+ # may also be an array of values to be selected when using a multiple select. # # Examples (call, result): @@ -217,24 +217,22 @@ module ActionView options_for_select(options, selected) end - # Returns a string of <tt><option></tt> tags, like <tt>#options_from_collection_for_select</tt>, but + # Returns a string of <tt><option></tt> tags, like <tt>options_from_collection_for_select</tt>, but # groups them by <tt><optgroup></tt> tags based on the object relationships of the arguments. # # Parameters: - # +collection+:: An array of objects representing the <tt><optgroup></tt> tags - # +group_method+:: The name of a method which, when called on a member of +collection+, returns an - # array of child objects representing the <tt><option></tt> tags - # +group_label_method+:: The name of a method which, when called on a member of +collection+, returns a - # string to be used as the +label+ attribute for its <tt><optgroup></tt> tag - # +option_key_method+:: The name of a method which, when called on a child object of a member of - # +collection+, returns a value to be used as the +value+ attribute for its - # <tt><option></tt> tag - # +option_value_method+:: The name of a method which, when called on a child object of a member of - # +collection+, returns a value to be used as the contents of its - # <tt><option></tt> tag - # +selected_key+:: A value equal to the +value+ attribute for one of the <tt><option></tt> tags, - # which will have the +selected+ attribute set. Corresponds to the return value - # of one of the calls to +option_key_method+. If +nil+, no selection is made. + # * +collection+ - An array of objects representing the <tt><optgroup></tt> tags. + # * +group_method+ - The name of a method which, when called on a member of +collection+, returns an + # array of child objects representing the <tt><option></tt> tags. + # * group_label_method+ - The name of a method which, when called on a member of +collection+, returns a + # string to be used as the +label+ attribute for its <tt><optgroup></tt> tag. + # * +option_key_method+ - The name of a method which, when called on a child object of a member of + # +collection+, returns a value to be used as the +value+ attribute for its <tt><option></tt> tag. + # * +option_value_method+ - The name of a method which, when called on a child object of a member of + # +collection+, returns a value to be used as the contents of its <tt><option></tt> tag. + # * +selected_key+ - A value equal to the +value+ attribute for one of the <tt><option></tt> tags, + # which will have the +selected+ attribute set. Corresponds to the return value of one of the calls + # to +option_key_method+. If +nil+, no selection is made. # # Example object structure for use with this method: # class Continent < ActiveRecord::Base @@ -300,8 +298,8 @@ module ActionView # a TimeZone. # # By default, +model+ is the TimeZone constant (which can be obtained - # in ActiveRecord as a value object). The only requirement is that the - # +model+ parameter be an object that responds to #all, and returns + # in Active Record as a value object). The only requirement is that the + # +model+ parameter be an object that responds to +all+, and returns # an array of objects that represent time zones. # # NOTE: Only the option tags are returned, you have to wrap this call in diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index 922a0662fe..ca58f4ba26 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -3,7 +3,7 @@ require 'action_view/helpers/tag_helper' module ActionView module Helpers - # Provides a number of methods for creating form tags that doesn't rely on an ActiveRecord object assigned to the template like + # Provides a number of methods for creating form tags that doesn't rely on an Active Record object assigned to the template like # FormHelper does. Instead, you provide the names and values manually. # # NOTE: The HTML options <tt>disabled</tt>, <tt>readonly</tt>, and <tt>multiple</tt> can all be treated as booleans. So specifying @@ -14,9 +14,9 @@ module ActionView # # ==== Options # * <tt>:multipart</tt> - If set to true, the enctype is set to "multipart/form-data". - # * <tt>:method</tt> - The method to use when submitting the form, usually either "get" or "post". - # If "put", "delete", or another verb is used, a hidden input with name _method - # is added to simulate the verb over post. + # * <tt>:method</tt> - The method to use when submitting the form, usually either "get" or "post". + # If "put", "delete", or another verb is used, a hidden input with name <tt>_method</tt> + # is added to simulate the verb over post. # * A list of parameters to feed to the URL the form will be posted to. # # ==== Examples diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb index 04bf5f2a30..602832e470 100644 --- a/actionpack/lib/action_view/helpers/prototype_helper.rb +++ b/actionpack/lib/action_view/helpers/prototype_helper.rb @@ -595,8 +595,8 @@ module ActionView # JavaScript sent with a Content-type of "text/javascript". # # Create new instances with PrototypeHelper#update_page or with - # ActionController::Base#render, then call #insert_html, #replace_html, - # #remove, #show, #hide, #visual_effect, or any other of the built-in + # ActionController::Base#render, then call +insert_html+, +replace_html+, + # +remove+, +show+, +hide+, +visual_effect+, or any other of the built-in # methods on the yielded generator in any order you like to modify the # content and appearance of the current page. # @@ -687,7 +687,7 @@ module ActionView end end - # Returns an object whose <tt>#to_json</tt> evaluates to +code+. Use this to pass a literal JavaScript + # Returns an object whose <tt>to_json</tt> evaluates to +code+. Use this to pass a literal JavaScript # expression as an argument to another JavaScriptGenerator method. def literal(code) ActiveSupport::JSON::Variable.new(code.to_s) @@ -1173,7 +1173,7 @@ module ActionView super(generator) end - # The JSON Encoder calls this to check for the #to_json method + # The JSON Encoder calls this to check for the +to_json+ method # Since it's a blank slate object, I suppose it responds to anything. def respond_to?(method) true diff --git a/actionpack/lib/action_view/helpers/record_tag_helper.rb b/actionpack/lib/action_view/helpers/record_tag_helper.rb index 40b66be79f..66c596f3a9 100644 --- a/actionpack/lib/action_view/helpers/record_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/record_tag_helper.rb @@ -2,7 +2,7 @@ module ActionView module Helpers module RecordTagHelper # Produces a wrapper DIV element with id and class parameters that - # relate to the specified ActiveRecord object. Usage example: + # relate to the specified Active Record object. Usage example: # # <% div_for(@person, :class => "foo") do %> # <%=h @person.name %> @@ -17,7 +17,7 @@ module ActionView end # content_tag_for creates an HTML element with id and class parameters - # that relate to the specified ActiveRecord object. For example: + # that relate to the specified Active Record object. For example: # # <% content_tag_for(:tr, @person) do %> # <td><%=h @person.first_name %></td> diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb index 6c0a7ec25c..b0dacfe964 100644 --- a/actionpack/lib/action_view/helpers/sanitize_helper.rb +++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb @@ -57,7 +57,7 @@ module ActionView self.class.white_list_sanitizer.sanitize(html, options) end - # Sanitizes a block of css code. Used by #sanitize when it comes across a style attribute + # Sanitizes a block of CSS code. Used by +sanitize+ when it comes across a style attribute. def sanitize_css(style) self.class.white_list_sanitizer.sanitize_css(style) end @@ -111,8 +111,8 @@ module ActionView end end - # Gets the HTML::FullSanitizer instance used by strip_tags. Replace with - # any object that responds to #sanitize + # Gets the HTML::FullSanitizer instance used by +strip_tags+. Replace with + # any object that responds to +sanitize+. # # Rails::Initializer.run do |config| # config.action_view.full_sanitizer = MySpecialSanitizer.new @@ -122,8 +122,8 @@ module ActionView @full_sanitizer ||= HTML::FullSanitizer.new end - # Gets the HTML::LinkSanitizer instance used by strip_links. Replace with - # any object that responds to #sanitize + # Gets the HTML::LinkSanitizer instance used by +strip_links+. Replace with + # any object that responds to +sanitize+. # # Rails::Initializer.run do |config| # config.action_view.link_sanitizer = MySpecialSanitizer.new @@ -133,8 +133,8 @@ module ActionView @link_sanitizer ||= HTML::LinkSanitizer.new end - # Gets the HTML::WhiteListSanitizer instance used by sanitize and sanitize_css. - # Replace with any object that responds to #sanitize + # Gets the HTML::WhiteListSanitizer instance used by sanitize and +sanitize_css+. + # Replace with any object that responds to +sanitize+. # # Rails::Initializer.run do |config| # config.action_view.white_list_sanitizer = MySpecialSanitizer.new @@ -144,7 +144,7 @@ module ActionView @white_list_sanitizer ||= HTML::WhiteListSanitizer.new end - # Adds valid HTML attributes that the #sanitize helper checks for URIs. + # Adds valid HTML attributes that the +sanitize+ helper checks for URIs. # # Rails::Initializer.run do |config| # config.action_view.sanitized_uri_attributes = 'lowsrc', 'target' @@ -154,7 +154,7 @@ module ActionView HTML::WhiteListSanitizer.uri_attributes.merge(attributes) end - # Adds to the Set of 'bad' tags for the #sanitize helper. + # Adds to the Set of 'bad' tags for the +sanitize+ helper. # # Rails::Initializer.run do |config| # config.action_view.sanitized_bad_tags = 'embed', 'object' @@ -163,7 +163,8 @@ module ActionView def sanitized_bad_tags=(attributes) HTML::WhiteListSanitizer.bad_tags.merge(attributes) end - # Adds to the Set of allowed tags for the #sanitize helper. + + # Adds to the Set of allowed tags for the +sanitize+ helper. # # Rails::Initializer.run do |config| # config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td' @@ -173,7 +174,7 @@ module ActionView HTML::WhiteListSanitizer.allowed_tags.merge(attributes) end - # Adds to the Set of allowed html attributes for the #sanitize helper. + # Adds to the Set of allowed HTML attributes for the +sanitize+ helper. # # Rails::Initializer.run do |config| # config.action_view.sanitized_allowed_attributes = 'onclick', 'longdesc' @@ -183,7 +184,7 @@ module ActionView HTML::WhiteListSanitizer.allowed_attributes.merge(attributes) end - # Adds to the Set of allowed css properties for the #sanitize and #sanitize_css heleprs. + # Adds to the Set of allowed CSS properties for the #sanitize and +sanitize_css+ heleprs. # # Rails::Initializer.run do |config| # config.action_view.sanitized_allowed_css_properties = 'expression' @@ -193,7 +194,7 @@ module ActionView HTML::WhiteListSanitizer.allowed_css_properties.merge(attributes) end - # Adds to the Set of allowed css keywords for the #sanitize and #sanitize_css helpers. + # Adds to the Set of allowed CSS keywords for the +sanitize+ and +sanitize_css+ helpers. # # Rails::Initializer.run do |config| # config.action_view.sanitized_allowed_css_keywords = 'expression' @@ -203,7 +204,7 @@ module ActionView HTML::WhiteListSanitizer.allowed_css_keywords.merge(attributes) end - # Adds to the Set of allowed shorthand css properties for the #sanitize and #sanitize_css helpers. + # Adds to the Set of allowed shorthand CSS properties for the +sanitize+ and +sanitize_css+ helpers. # # Rails::Initializer.run do |config| # config.action_view.sanitized_shorthand_css_properties = 'expression' @@ -213,7 +214,7 @@ module ActionView HTML::WhiteListSanitizer.shorthand_css_properties.merge(attributes) end - # Adds to the Set of allowed protocols for the #sanitize helper. + # Adds to the Set of allowed protocols for the +sanitize+ helper. # # Rails::Initializer.run do |config| # config.action_view.sanitized_allowed_protocols = 'ssh', 'feed' diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb index 12b4cfd3f8..c9b2761cb8 100644 --- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb +++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb @@ -26,9 +26,9 @@ module ActionView # :url => { :action => "reload" }, # :complete => visual_effect(:highlight, "posts", :duration => 0.5) # - # If no element_id is given, it assumes "element" which should be a local + # If no +element_id+ is given, it assumes "element" which should be a local # variable in the generated JavaScript execution context. This can be - # used for example with drop_receiving_element: + # used for example with +drop_receiving_element+: # # <%= drop_receiving_element (...), :loading => visual_effect(:fade) %> # @@ -67,6 +67,7 @@ module ActionView # element as parameters. # # Example: + # # <%= sortable_element("my_list", :url => { :action => "order" }) %> # # In the example, the action gets a "my_list" array parameter @@ -79,60 +80,56 @@ module ActionView # # Additional +options+ are: # - # <tt>:format</tt>:: A regular expression to determine what to send - # as the serialized id to the server (the default - # is <tt>/^[^_]*_(.*)$/</tt>). - # - # <tt>:constraint</tt>:: Whether to constrain the dragging to either <tt>:horizontal</tt> - # or <tt>:vertical</tt> (or false to make it unconstrained). - # - # <tt>:overlap</tt>:: Calculate the item overlap in the <tt>:horizontal</tt> or - # <tt>:vertical</tt> direction. - # - # <tt>:tag</tt>:: Which children of the container element to treat as - # sortable (default is <tt>li</tt>). - # - # <tt>:containment</tt>:: Takes an element or array of elements to treat as - # potential drop targets (defaults to the original - # target element). - # - # <tt>:only</tt>:: A CSS class name or arry of class names used to filter - # out child elements as candidates. - # - # <tt>:scroll</tt>:: Determines whether to scroll the list during drag - # operations if the list runs past the visual border. - # - # <tt>:tree</tt>:: Determines whether to treat nested lists as part of the - # main sortable list. This means that you can create multi- - # layer lists, and not only sort items at the same level, - # but drag and sort items between levels. - # - # <tt>:hoverclass</tt>:: If set, the Droppable will have this additional CSS class - # when an accepted Draggable is hovered over it. - # - # <tt>:handle</tt>:: Sets whether the element should only be draggable by an - # embedded handle. The value may be a string referencing a - # CSS class value (as of script.aculo.us V1.5). The first - # child/grandchild/etc. element found within the element - # that has this CSS class value will be used as the handle. - # - # <tt>:ghosting</tt>:: Clones the element and drags the clone, leaving the original - # in place until the clone is dropped (default is <tt>false</tt>). - # - # <tt>:dropOnEmpty</tt>:: If set to true, the Sortable container will be made into - # a Droppable, that can receive a Draggable (as according to - # the containment rules) as a child element when there are no - # more elements inside (default is <tt>false</tt>). - # - # <tt>:onChange</tt>:: Called whenever the sort order changes while dragging. When - # dragging from one Sortable to another, the callback is - # called once on each Sortable. Gets the affected element as - # its parameter. - # - # <tt>:onUpdate</tt>:: Called when the drag ends and the Sortable's order is - # changed in any way. When dragging from one Sortable to - # another, the callback is called once on each Sortable. Gets - # the container as its parameter. + # * <tt>:format</tt> - A regular expression to determine what to send as the + # serialized id to the server (the default is <tt>/^[^_]*_(.*)$/</tt>). + # + # * <tt>:constraint</tt> - Whether to constrain the dragging to either + # <tt>:horizontal</tt> or <tt>:vertical</tt> (or false to make it unconstrained). + # + # * <tt>:overlap</tt> - Calculate the item overlap in the <tt>:horizontal</tt> + # or <tt>:vertical</tt> direction. + # + # * <tt>:tag</tt> - Which children of the container element to treat as + # sortable (default is <tt>li</tt>). + # + # * <tt>:containment</tt> - Takes an element or array of elements to treat as + # potential drop targets (defaults to the original target element). + # + # * <tt>:only</tt> - A CSS class name or arry of class names used to filter + # out child elements as candidates. + # + # * <tt>:scroll</tt> - Determines whether to scroll the list during drag + # operations if the list runs past the visual border. + # + # * <tt>:tree</tt> - Determines whether to treat nested lists as part of the + # main sortable list. This means that you can create multi-layer lists, + # and not only sort items at the same level, but drag and sort items + # between levels. + # + # * <tt>:hoverclass</tt> - If set, the Droppable will have this additional CSS class + # when an accepted Draggable is hovered over it. + # + # * <tt>:handle</tt> - Sets whether the element should only be draggable by an + # embedded handle. The value may be a string referencing a CSS class value + # (as of script.aculo.us V1.5). The first child/grandchild/etc. element + # found within the element that has this CSS class value will be used as + # the handle. + # + # * <tt>:ghosting</tt> - Clones the element and drags the clone, leaving + # the original in place until the clone is dropped (default is <tt>false</tt>). + # + # * <tt>:dropOnEmpty</tt> - If true the Sortable container will be made into + # a Droppable, that can receive a Draggable (as according to the containment + # rules) as a child element when there are no more elements inside (default + # is <tt>false</tt>). + # + # * <tt>:onChange</tt> - Called whenever the sort order changes while dragging. When + # dragging from one Sortable to another, the callback is called once on each + # Sortable. Gets the affected element as its parameter. + # + # * <tt>:onUpdate</tt> - Called when the drag ends and the Sortable's order is + # changed in any way. When dragging from one Sortable to another, the callback + # is called once on each Sortable. Gets the container as its parameter. # # See http://script.aculo.us for more documentation. def sortable_element(element_id, options = {}) @@ -170,8 +167,8 @@ module ActionView end # Makes the element with the DOM ID specified by +element_id+ receive - # dropped draggable elements (created by draggable_element). - # and make an AJAX call By default, the action called gets the DOM ID + # dropped draggable elements (created by +draggable_element+). + # and make an AJAX call. By default, the action called gets the DOM ID # of the element as parameter. # # Example: @@ -182,32 +179,30 @@ module ActionView # http://script.aculo.us for more documentation. # # Some of these +options+ include: - # <tt>:accept</tt>:: Set this to a string or an array of strings describing the - # allowable CSS classes that the draggable_element must have in order - # to be accepted by this drop_receiving_element. - # - # <tt>:confirm</tt>:: Adds a confirmation dialog. - # - # Example: - # :confirm => "Are you sure you want to do this?" - # - # <tt>:hoverclass</tt>:: If set, the drop_receiving_element will have this additional CSS class - # when an accepted draggable_element is hovered over it. - # - # <tt>:onDrop</tt>:: Called when a draggable_element is dropped onto this element. - # Override this callback with a javascript expression to - # change the default drop behavour. - # - # Example: - # :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }" - # - # This callback gets three parameters: - # The +Draggable+ element, the +Droppable+ element and the - # +Event+ object. You can extract additional information about the - # drop - like if the Ctrl or Shift keys were pressed - from the +Event+ object. - # - # <tt>:with</tt>:: A JavaScript expression specifying the parameters for the XMLHttpRequest. - # Any expressions should return a valid URL query string. + # * <tt>:accept</tt> - Set this to a string or an array of strings describing the + # allowable CSS classes that the +draggable_element+ must have in order + # to be accepted by this +drop_receiving_element+. + # + # * <tt>:confirm</tt> - Adds a confirmation dialog. Example: + # + # :confirm => "Are you sure you want to do this?" + # + # * <tt>:hoverclass</tt> - If set, the +drop_receiving_element+ will have + # this additional CSS class when an accepted +draggable_element+ is + # hovered over it. + # + # * <tt>:onDrop</tt> - Called when a +draggable_element+ is dropped onto + # this element. Override this callback with a JavaScript expression to + # change the default drop behavour. Example: + # + # :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }" + # + # This callback gets three parameters: The Draggable element, the Droppable + # element and the Event object. You can extract additional information about + # the drop - like if the Ctrl or Shift keys were pressed - from the Event object. + # + # * <tt>:with</tt> - A JavaScript expression specifying the parameters for + # the XMLHttpRequest. Any expressions should return a valid URL query string. def drop_receiving_element(element_id, options = {}) javascript_tag(drop_receiving_element_js(element_id, options).chop!) end diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb index 38c8d18cb0..4b12adf225 100644 --- a/actionpack/lib/action_view/helpers/url_helper.rb +++ b/actionpack/lib/action_view/helpers/url_helper.rb @@ -10,7 +10,7 @@ module ActionView include JavaScriptHelper # Returns the URL for the set of +options+ provided. This takes the - # same options as url_for in ActionController (see the + # same options as +url_for+ in Action Controller (see the # documentation for ActionController::Base#url_for). Note that by default # <tt>:only_path</tt> is <tt>true</tt> so you'll get the relative /controller/action # instead of the fully qualified URL like http://example.com/controller/action. diff --git a/actionpack/lib/action_view/template.rb b/actionpack/lib/action_view/template.rb index 2cda3d94b5..369526188f 100644 --- a/actionpack/lib/action_view/template.rb +++ b/actionpack/lib/action_view/template.rb @@ -93,9 +93,9 @@ module ActionView #:nodoc: # Register a class that knows how to handle template files with the given # extension. This can be used to implement new template types. # The constructor for the class must take the ActiveView::Base instance - # as a parameter, and the class must implement a #render method that + # as a parameter, and the class must implement a +render+ method that # takes the contents of the template to render as well as the Hash of - # local assigns available to the template. The #render method ought to + # local assigns available to the template. The +render+ method ought to # return the rendered template as a string. def self.register_template_handler(extension, klass) @@template_handlers[extension.to_sym] = klass diff --git a/activerecord/lib/active_record/aggregations.rb b/activerecord/lib/active_record/aggregations.rb index 61446cde36..a5d3a50ef1 100644 --- a/activerecord/lib/active_record/aggregations.rb +++ b/activerecord/lib/active_record/aggregations.rb @@ -92,19 +92,19 @@ module ActiveRecord # # == Writing value objects # - # Value objects are immutable and interchangeable objects that represent a given value, such as a +Money+ object representing - # $5. Two +Money+ objects both representing $5 should be equal (through methods such as == and <=> from +Comparable+ if ranking - # makes sense). This is unlike entity objects where equality is determined by identity. An entity class such as +Customer+ can + # Value objects are immutable and interchangeable objects that represent a given value, such as a Money object representing + # $5. Two Money objects both representing $5 should be equal (through methods such as <tt>==</tt> and <tt><=></tt> from Comparable if ranking + # makes sense). This is unlike entity objects where equality is determined by identity. An entity class such as Customer can # easily have two different objects that both have an address on Hyancintvej. Entity identity is determined by object or - # relational unique identifiers (such as primary keys). Normal <tt>ActiveRecord::Base</tt> classes are entity objects. + # relational unique identifiers (such as primary keys). Normal ActiveRecord::Base classes are entity objects. # - # It's also important to treat the value objects as immutable. Don't allow the +Money+ object to have its amount changed after - # creation. Create a new +Money+ object with the new value instead. This is exemplified by the <tt>Money#exchanged_to</tt> method that + # It's also important to treat the value objects as immutable. Don't allow the Money object to have its amount changed after + # creation. Create a new Money object with the new value instead. This is exemplified by the Money#exchanged_to method that # returns a new value object instead of changing its own values. Active Record won't persist value objects that have been # changed through means other than the writer method. # # The immutable requirement is enforced by Active Record by freezing any object assigned as a value object. Attempting to - # change it afterwards will result in a <tt>ActiveSupport::FrozenObjectError</tt>. + # change it afterwards will result in a ActiveSupport::FrozenObjectError. # # Read more about value objects on http://c2.com/cgi/wiki?ValueObject and on the dangers of not keeping value objects # immutable on http://c2.com/cgi/wiki?ValueObjectsShouldBeImmutable @@ -123,8 +123,8 @@ module ActiveRecord # # Options are: # * <tt>:class_name</tt> - specify the class name of the association. Use it only if that name can't be inferred - # from the part id. So <tt>composed_of :address</tt> will by default be linked to the +Address+ class, but - # if the real class name is +CompanyAddress+, you'll have to specify it with this option. + # from the part id. So <tt>composed_of :address</tt> will by default be linked to the Address class, but + # if the real class name is CompanyAddress, you'll have to specify it with this option. # * <tt>:mapping</tt> - specifies a number of mapping arrays (attribute, parameter) that bind an attribute name # to a constructor parameter on the value class. # * <tt>:allow_nil</tt> - specifies that the aggregate object will not be instantiated when all mapped diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 6c21fed8ea..a3d1bbbada 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -155,7 +155,7 @@ module ActiveRecord # # == Cardinality and associations # - # ActiveRecord associations can be used to describe one-to-one, one-to-many and many-to-many + # Active Record associations can be used to describe one-to-one, one-to-many and many-to-many # relationships between models. Each model uses an association to describe its role in # the relation. The +belongs_to+ association is always used in the model that has # the foreign key. @@ -441,9 +441,9 @@ module ActiveRecord # # == Eager loading of associations # - # Eager loading is a way to find objects of a certain class and a number of named associations along with it in a single SQL call. This is + # Eager loading is a way to find objects of a certain class and a number of named associations. This is # one of the easiest ways of to prevent the dreaded 1+N problem in which fetching 100 posts that each need to display their author - # triggers 101 database queries. Through the use of eager loading, the 101 queries can be reduced to 1. Example: + # triggers 101 database queries. Through the use of eager loading, the 101 queries can be reduced to 2. Example: # # class Post < ActiveRecord::Base # belongs_to :author @@ -452,7 +452,7 @@ module ActiveRecord # # Consider the following loop using the class above: # - # for post in Post.find(:all) + # for post in Post.all # puts "Post: " + post.title # puts "Written by: " + post.author.name # puts "Last comment on: " + post.comments.first.created_on @@ -462,14 +462,15 @@ module ActiveRecord # # for post in Post.find(:all, :include => :author) # - # This references the name of the +belongs_to+ association that also used the <tt>:author</tt> symbol, so the find will now weave in a join something - # like this: <tt>LEFT OUTER JOIN authors ON authors.id = posts.author_id</tt>. Doing so will cut down the number of queries from 201 to 101. + # This references the name of the +belongs_to+ association that also used the <tt>:author</tt> symbol. After loading the posts, find + # will collect the +author_id+ from each one and load all the referenced authors with one query. Doing so will cut down the number of queries from 201 to 102. # # We can improve upon the situation further by referencing both associations in the finder with: # # for post in Post.find(:all, :include => [ :author, :comments ]) # - # That'll add another join along the lines of: <tt>LEFT OUTER JOIN comments ON comments.post_id = posts.id</tt>. And we'll be down to 1 query. + # This will load all comments with a single query. This reduces the total number of queries to 3. More generally the number of queries + # will be 1 plus the number of associations named (except if some of the associations are polymorphic +belongs_to+ - see below). # # To include a deep hierarchy of associations, use a hash: # @@ -482,81 +483,91 @@ module ActiveRecord # the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So it's no # catch-all for performance problems, but it's a great way to cut down on the number of queries in a situation as the one described above. # - # Since the eager loading pulls from multiple tables, you'll have to disambiguate any column references in both conditions and orders. So - # <tt>:order => "posts.id DESC"</tt> will work while <tt>:order => "id DESC"</tt> will not. Because eager loading generates the +SELECT+ statement too, the - # <tt>:select</tt> option is ignored. + # Since only one table is loaded at a time, conditions or orders cannot reference tables other than the main one. If this is the case + # Active Record falls back to the previously used LEFT OUTER JOIN based strategy. For example + # + # Post.find(:all, :include => [ :author, :comments ], :conditions => ['comments.approved = ?', true]) # - # You can use eager loading on multiple associations from the same table, but you cannot use those associations in orders and conditions - # as there is currently not any way to disambiguate them. Eager loading will not pull additional attributes on join tables, so "rich - # associations" with +has_and_belongs_to_many+ are not a good fit for eager loading. + # will result in a single SQL query with joins along the lines of: <tt>LEFT OUTER JOIN comments ON comments.post_id = posts.id</tt> and + # <tt>LEFT OUTER JOIN authors ON authors.id = posts.author_id</tt>. Note that using conditions like this can have unintended consequences. + # In the above example posts with no approved comments are not returned at all, because the conditions apply to the SQL statement as a whole + # and not just to the association. You must disambiguate column references for this fallback to happen, for example + # <tt>:order => "author.name DESC"</tt> will work but <tt>:order => "name DESC"</tt> will not. + # + # If you do want eagerload only some members of an association it is usually more natural to <tt>:include</tt> an association + # which has conditions defined on it: + # + # class Post < ActiveRecord::Base + # has_many :approved_comments, :class_name => 'Comment', :conditions => ['approved = ?', true] + # end + # + # Post.find(:all, :include => :approved_comments) + # + # will load posts and eager load the +approved_comments+ association, which contains only those comments that have been approved. # # When eager loaded, conditions are interpolated in the context of the model class, not the model instance. Conditions are lazily interpolated # before the actual model exists. # - # Eager loading is not supported with polymorphic associations up to (and including) - # version 2.0.2. Given + # Eager loading is supported with polymorphic associations. # # class Address < ActiveRecord::Base # belongs_to :addressable, :polymorphic => true # end # - # a call that tries to eager load the addressable model - # - # Address.find(:all, :include => :addressable) # INVALID - # - # will raise ActiveRecord::EagerLoadPolymorphicError. The reason is that the parent model's type - # is a column value so its corresponding table name cannot be put in the +FROM+/+JOIN+ clauses of that early query. + # A call that tries to eager load the addressable model # - # In versions greater than 2.0.2 eager loading in polymorphic associations is supported - # thanks to a change in the overall preloading strategy. + # Address.find(:all, :include => :addressable) # - # It does work the other way around though: if the <tt>User</tt> model is <tt>addressable</tt> you can eager load - # their addresses with <tt>:include</tt> just fine, every piece needed to construct the query is known beforehand. + # will execute one query to load the addresses and load the addressables with one query per addressable type. + # For example if all the addressables are either of class Person or Company then a total of 3 queries will be executed. The list of + # addressable types to load is determined on the back of the addresses loaded. This is not supported if Active Record has to fallback + # to the previous implementation of eager loading and will raise ActiveRecord::EagerLoadPolymorphicError. The reason is that the parent + # model's type is a column value so its corresponding table name cannot be put in the +FROM+/+JOIN+ clauses of that query. # # == Table Aliasing # - # ActiveRecord uses table aliasing in the case that a table is referenced multiple times in a join. If a table is referenced only once, + # Active Record uses table aliasing in the case that a table is referenced multiple times in a join. If a table is referenced only once, # the standard table name is used. The second time, the table is aliased as <tt>#{reflection_name}_#{parent_table_name}</tt>. Indexes are appended # for any more successive uses of the table name. # - # Post.find :all, :include => :comments - # # => SELECT ... FROM posts LEFT OUTER JOIN comments ON ... - # Post.find :all, :include => :special_comments # STI - # # => SELECT ... FROM posts LEFT OUTER JOIN comments ON ... AND comments.type = 'SpecialComment' - # Post.find :all, :include => [:comments, :special_comments] # special_comments is the reflection name, posts is the parent table name - # # => SELECT ... FROM posts LEFT OUTER JOIN comments ON ... LEFT OUTER JOIN comments special_comments_posts + # Post.find :all, :joins => :comments + # # => SELECT ... FROM posts INNER JOIN comments ON ... + # Post.find :all, :joins => :special_comments # STI + # # => SELECT ... FROM posts INNER JOIN comments ON ... AND comments.type = 'SpecialComment' + # Post.find :all, :joins => [:comments, :special_comments] # special_comments is the reflection name, posts is the parent table name + # # => SELECT ... FROM posts INNER JOIN comments ON ... INNER JOIN comments special_comments_posts # # Acts as tree example: # - # TreeMixin.find :all, :include => :children - # # => SELECT ... FROM mixins LEFT OUTER JOIN mixins childrens_mixins ... - # TreeMixin.find :all, :include => {:children => :parent} # using cascading eager includes - # # => SELECT ... FROM mixins LEFT OUTER JOIN mixins childrens_mixins ... - # LEFT OUTER JOIN parents_mixins ... - # TreeMixin.find :all, :include => {:children => {:parent => :children}} - # # => SELECT ... FROM mixins LEFT OUTER JOIN mixins childrens_mixins ... - # LEFT OUTER JOIN parents_mixins ... - # LEFT OUTER JOIN mixins childrens_mixins_2 + # TreeMixin.find :all, :joins => :children + # # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ... + # TreeMixin.find :all, :joins => {:children => :parent} + # # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ... + # INNER JOIN parents_mixins ... + # TreeMixin.find :all, :joins => {:children => {:parent => :children}} + # # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ... + # INNER JOIN parents_mixins ... + # INNER JOIN mixins childrens_mixins_2 # # Has and Belongs to Many join tables use the same idea, but add a <tt>_join</tt> suffix: # - # Post.find :all, :include => :categories - # # => SELECT ... FROM posts LEFT OUTER JOIN categories_posts ... LEFT OUTER JOIN categories ... - # Post.find :all, :include => {:categories => :posts} - # # => SELECT ... FROM posts LEFT OUTER JOIN categories_posts ... LEFT OUTER JOIN categories ... - # LEFT OUTER JOIN categories_posts posts_categories_join LEFT OUTER JOIN posts posts_categories - # Post.find :all, :include => {:categories => {:posts => :categories}} - # # => SELECT ... FROM posts LEFT OUTER JOIN categories_posts ... LEFT OUTER JOIN categories ... - # LEFT OUTER JOIN categories_posts posts_categories_join LEFT OUTER JOIN posts posts_categories - # LEFT OUTER JOIN categories_posts categories_posts_join LEFT OUTER JOIN categories categories_posts + # Post.find :all, :joins => :categories + # # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ... + # Post.find :all, :joins => {:categories => :posts} + # # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ... + # INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories + # Post.find :all, :joins => {:categories => {:posts => :categories}} + # # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ... + # INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories + # INNER JOIN categories_posts categories_posts_join INNER JOIN categories categories_posts_2 # # If you wish to specify your own custom joins using a <tt>:joins</tt> option, those table names will take precedence over the eager associations: # - # Post.find :all, :include => :comments, :joins => "inner join comments ..." - # # => SELECT ... FROM posts LEFT OUTER JOIN comments_posts ON ... INNER JOIN comments ... - # Post.find :all, :include => [:comments, :special_comments], :joins => "inner join comments ..." - # # => SELECT ... FROM posts LEFT OUTER JOIN comments comments_posts ON ... - # LEFT OUTER JOIN comments special_comments_posts ... + # Post.find :all, :joins => :comments, :joins => "inner join comments ..." + # # => SELECT ... FROM posts INNER JOIN comments_posts ON ... INNER JOIN comments ... + # Post.find :all, :joins => [:comments, :special_comments], :joins => "inner join comments ..." + # # => SELECT ... FROM posts INNER JOIN comments comments_posts ON ... + # INNER JOIN comments special_comments_posts ... # INNER JOIN comments ... # # Table aliases are automatically truncated according to the maximum length of table identifiers according to the specific database. @@ -842,7 +853,6 @@ module ActiveRecord # this results in a counter with +NULL+ value, which will never increment. # Note: Specifying a counter cache will add it to that model's list of readonly attributes using +attr_readonly+. # * <tt>:include</tt> - Specify second-order associations that should be eager loaded when this object is loaded. - # Not allowed if the association is polymorphic. # * <tt>:polymorphic</tt> - Specify this association is a polymorphic association by passing +true+. # Note: If you've enabled the counter cache, then you may want to add the counter cache attribute # to the +attr_readonly+ list in the associated classes (e.g. <tt>class Post; attr_readonly :comments_count; end</tt>). @@ -942,7 +952,7 @@ module ActiveRecord # # Deprecated: Any additional fields added to the join table will be placed as attributes when pulling records out through # +has_and_belongs_to_many+ associations. Records returned from join tables with additional attributes will be marked as - # +ReadOnly+ (because we can't save changes to the additional attributes). It's strongly recommended that you upgrade any + # readonly (because we can't save changes to the additional attributes). It's strongly recommended that you upgrade any # associations with attributes to a real join model (see introduction). # # Adds the following methods for retrieval and query: diff --git a/activerecord/lib/active_record/associations/association_collection.rb b/activerecord/lib/active_record/associations/association_collection.rb index 2f03197012..52d2a9864e 100644 --- a/activerecord/lib/active_record/associations/association_collection.rb +++ b/activerecord/lib/active_record/associations/association_collection.rb @@ -48,7 +48,7 @@ module ActiveRecord end end - # fetch first using SQL if possible + # Fetches the first one using SQL if possible. def first(*args) if fetch_first_or_last_using_find? args find(:first, *args) @@ -58,7 +58,7 @@ module ActiveRecord end end - # fetch last using SQL if possible + # Fetches the last one using SQL if possible. def last(*args) if fetch_first_or_last_using_find? args find(:last, *args) diff --git a/activerecord/lib/active_record/associations/has_many_through_association.rb b/activerecord/lib/active_record/associations/has_many_through_association.rb index f683669615..ebcf462f2e 100644 --- a/activerecord/lib/active_record/associations/has_many_through_association.rb +++ b/activerecord/lib/active_record/associations/has_many_through_association.rb @@ -34,7 +34,7 @@ module ActiveRecord def count(*args) column_name, options = @reflection.klass.send(:construct_count_options_from_args, *args) if @reflection.options[:uniq] - # This is needed because 'SELECT count(DISTINCT *)..' is not valid sql statement. + # This is needed because 'SELECT count(DISTINCT *)..' is not valid SQL statement. column_name = "#{@reflection.quoted_table_name}.#{@reflection.klass.primary_key}" if column_name == :all options.merge!(:distinct => true) end diff --git a/activerecord/lib/active_record/attribute_methods.rb b/activerecord/lib/active_record/attribute_methods.rb index d753778d52..fab16a4446 100644 --- a/activerecord/lib/active_record/attribute_methods.rb +++ b/activerecord/lib/active_record/attribute_methods.rb @@ -94,7 +94,7 @@ module ActiveRecord end # Checks whether the method is defined in the model or any of its subclasses - # that also derive from ActiveRecord. Raises DangerousAttributeError if the + # that also derive from Active Record. Raises DangerousAttributeError if the # method is defined by Active Record though. def instance_method_already_implemented?(method_name) method_name = method_name.to_s @@ -162,8 +162,8 @@ module ActiveRecord evaluate_attribute_method attr_name, "def #{attr_name}; unserialize_attribute('#{attr_name}'); end" end - # Defined for all datetime and timestamp attributes when time_zone_aware_attributes are enabled. - # This enhanced read method automatically converts the UTC time stored in the database to the time zone stored in Time.zone + # Defined for all +datetime+ and +timestamp+ attributes when +time_zone_aware_attributes+ are enabled. + # This enhanced read method automatically converts the UTC time stored in the database to the time zone stored in Time.zone. def define_read_method_for_time_zone_conversion(attr_name) method_body = <<-EOV def #{attr_name}(reload = false) @@ -176,7 +176,7 @@ module ActiveRecord evaluate_attribute_method attr_name, method_body end - # Define an attribute ? method. + # Defines a predicate method <tt>attr_name?</tt>. def define_question_method(attr_name) evaluate_attribute_method attr_name, "def #{attr_name}?; query_attribute('#{attr_name}'); end", "#{attr_name}?" end @@ -185,7 +185,7 @@ module ActiveRecord evaluate_attribute_method attr_name, "def #{attr_name}=(new_value);write_attribute('#{attr_name}', new_value);end", "#{attr_name}=" end - # Defined for all datetime and timestamp attributes when time_zone_aware_attributes are enabled. + # Defined for all +datetime+ and +timestamp+ attributes when +time_zone_aware_attributes+ are enabled. # This enhanced write method will automatically convert the time passed to it to the zone stored in Time.zone. def define_write_method_for_time_zone_conversion(attr_name) method_body = <<-EOV diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 5351f55200..c393128621 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -2,7 +2,7 @@ require 'yaml' require 'set' module ActiveRecord #:nodoc: - # Generic ActiveRecord exception class. + # Generic Active Record exception class. class ActiveRecordError < StandardError end @@ -30,19 +30,19 @@ module ActiveRecord #:nodoc: class SerializationTypeMismatch < ActiveRecordError end - # Raised when adapter not specified on connection (or configuration file config/database.yml misses adapter field). + # Raised when adapter not specified on connection (or configuration file <tt>config/database.yml</tt> misses adapter field). class AdapterNotSpecified < ActiveRecordError end - # Raised when ActiveRecord cannot find database adapter specified in config/database.yml or programmatically. + # Raised when Active Record cannot find database adapter specified in <tt>config/database.yml</tt> or programmatically. class AdapterNotFound < ActiveRecordError end - # Raised when connection to the database could not been established (for example when connection= is given a nil object). + # Raised when connection to the database could not been established (for example when <tt>connection=</tt> is given a nil object). class ConnectionNotEstablished < ActiveRecordError end - # Raised when ActiveRecord cannot find record by given id or set of ids. + # Raised when Active Record cannot find record by given id or set of ids. class RecordNotFound < ActiveRecordError end @@ -70,7 +70,7 @@ module ActiveRecord #:nodoc: # instantiation, for example, when two users edit the same wiki page and one starts editing and saves # the page before the other. # - # Read more about optimistic locking in +ActiveRecord::Locking+ module RDoc. + # Read more about optimistic locking in ActiveRecord::Locking module RDoc. class StaleObjectError < ActiveRecordError end @@ -83,12 +83,12 @@ module ActiveRecord #:nodoc: class ReadOnlyRecord < ActiveRecordError end - # Used by ActiveRecord transaction mechanism to distinguish rollback from other exceptional situations. + # Used by Active Record transaction mechanism to distinguish rollback from other exceptional situations. # You can use it to roll your transaction back explicitly in the block passed to +transaction+ method. class Rollback < ActiveRecordError end - # Raised when attribute has a name reserved by ActiveRecord (when attribute has name of one of ActiveRecord instance methods). + # Raised when attribute has a name reserved by Active Record (when attribute has name of one of Active Record instance methods). class DangerousAttributeError < ActiveRecordError end @@ -200,7 +200,7 @@ module ActiveRecord #:nodoc: # # All column values are automatically available through basic accessors on the Active Record object, but sometimes you # want to specialize this behavior. This can be done by overwriting the default accessors (using the same - # name as the attribute) and calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things. + # name as the attribute) and calling <tt>read_attribute(attr_name)</tt> and <tt>write_attribute(attr_name, value)</tt> to actually change things. # Example: # # class Song < ActiveRecord::Base @@ -215,8 +215,8 @@ module ActiveRecord #:nodoc: # end # end # - # You can alternatively use self[:attribute]=(value) and self[:attribute] instead of write_attribute(:attribute, value) and - # read_attribute(:attribute) as a shorter form. + # You can alternatively use <tt>self[:attribute]=(value)</tt> and <tt>self[:attribute]</tt> instead of <tt>write_attribute(:attribute, value)</tt> and + # <tt>read_attribute(:attribute)</tt> as a shorter form. # # == Attribute query methods # @@ -236,7 +236,7 @@ module ActiveRecord #:nodoc: # # Sometimes you want to be able to read the raw attribute data without having the column-determined typecast run its course first. # That can be done by using the <tt><attribute>_before_type_cast</tt> accessors that all attributes have. For example, if your Account model - # has a balance attribute, you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>. + # has a <tt>balance</tt> attribute, you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>. # # This is especially useful in validation situations where the user might supply a string for an integer field and you want to display # the original string back in an error message. Accessing the attribute normally would typecast the string to 0, which isn't what you @@ -245,8 +245,8 @@ module ActiveRecord #:nodoc: # == Dynamic attribute-based finders # # Dynamic attribute-based finders are a cleaner way of getting (and/or creating) objects by simple queries without turning to SQL. They work by - # appending the name of an attribute to <tt>find_by_</tt> or <tt>find_all_by_</tt>, so you get finders like Person.find_by_user_name, - # Person.find_all_by_last_name, Payment.find_by_transaction_id. So instead of writing + # appending the name of an attribute to <tt>find_by_</tt> or <tt>find_all_by_</tt>, so you get finders like <tt>Person.find_by_user_name</tt>, + # <tt>Person.find_all_by_last_name</tt>, and <tt>Payment.find_by_transaction_id</tt>. So instead of writing # <tt>Person.find(:first, :conditions => ["user_name = ?", user_name])</tt>, you just do <tt>Person.find_by_user_name(user_name)</tt>. # And instead of writing <tt>Person.find(:all, :conditions => ["last_name = ?", last_name])</tt>, you just do <tt>Person.find_all_by_last_name(last_name)</tt>. # @@ -255,8 +255,8 @@ module ActiveRecord #:nodoc: # <tt>Person.find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])</tt>, you just do # <tt>Person.find_by_user_name_and_password(user_name, password)</tt>. # - # It's even possible to use all the additional parameters to find. For example, the full interface for Payment.find_all_by_amount - # is actually Payment.find_all_by_amount(amount, options). And the full interface to Person.find_by_user_name is + # It's even possible to use all the additional parameters to find. For example, the full interface for <tt>Payment.find_all_by_amount</tt> + # is actually <tt>Payment.find_all_by_amount(amount, options)</tt>. And the full interface to <tt>Person.find_by_user_name</tt> is # actually <tt>Person.find_by_user_name(user_name, options)</tt>. So you could call <tt>Payment.find_all_by_amount(50, :order => "created_on")</tt>. # # The same dynamic finder style can be used to create the object if it doesn't already exist. This dynamic finder is called with @@ -316,8 +316,8 @@ module ActiveRecord #:nodoc: # class Client < Company; end # class PriorityClient < Client; end # - # When you do Firm.create(:name => "37signals"), this record will be saved in the companies table with type = "Firm". You can then - # fetch this row again using Company.find(:first, "name = '37signals'") and it will return a Firm object. + # When you do <tt>Firm.create(:name => "37signals")</tt>, this record will be saved in the companies table with type = "Firm". You can then + # fetch this row again using <tt>Company.find(:first, "name = '37signals'")</tt> and it will return a Firm object. # # If you don't have a type column defined in your table, single-table inheritance won't be triggered. In that case, it'll work just # like normal subclasses with no special magic for differentiating between them or reloading the right type with find. @@ -329,8 +329,8 @@ module ActiveRecord #:nodoc: # # Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection. # All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection. - # For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say Course.establish_connection - # and Course *and all its subclasses* will use this connection instead. + # For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say <tt>Course.establish_connection</tt> + # and Course and all of its subclasses will use this connection instead. # # This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is # requested, the retrieve_connection method will go up the class-hierarchy until a connection is found in the connection pool. @@ -407,7 +407,7 @@ module ActiveRecord #:nodoc: @@table_name_suffix = "" # Indicates whether table names should be the pluralized versions of the corresponding class names. - # If true, the default table name for a +Product+ class will be +products+. If false, it would just be +product+. + # If true, the default table name for a Product class will be +products+. If false, it would just be +product+. # See table_name for the full rules on table/class naming. This is true, by default. cattr_accessor :pluralize_table_names, :instance_writer => false @@pluralize_table_names = true @@ -446,36 +446,44 @@ module ActiveRecord #:nodoc: class << self # Class methods # Find operates with four different retrieval approaches: # - # * Find by id: This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]). + # * Find by id - This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]). # If no record can be found for all of the listed ids, then RecordNotFound will be raised. - # * Find first: This will return the first record matched by the options used. These options can either be specific - # conditions or merely an order. If no record can be matched, nil is returned. - # * Find last: This will return the last record matched by the options used. These options can either be specific - # conditions or merely an order. If no record can be matched, nil is returned. - # * Find all: This will return all the records matched by the options used. If no records are found, an empty array is returned. - # - # All approaches accept an options hash as their last parameter. The options are: - # - # * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro. - # * <tt>:order</tt>: An SQL fragment like "created_at DESC, name". - # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause. - # * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned. - # * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip rows 0 through 4. - # * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed) - # or named associations in the same form used for the <tt>:include</tt> option, which will perform an INNER JOIN on the associated table(s). + # * Find first - This will return the first record matched by the options used. These options can either be specific + # conditions or merely an order. If no record can be matched, +nil+ is returned. Use + # <tt>Model.find(:first, *args)</tt> or its shortcut <tt>Model.first(*args)</tt>. + # * Find last - This will return the last record matched by the options used. These options can either be specific + # conditions or merely an order. If no record can be matched, +nil+ is returned. Use + # <tt>Model.find(:last, *args)</tt> or its shortcut <tt>Model.last(*args)</tt>. + # * Find all - This will return all the records matched by the options used. + # If no records are found, an empty array is returned. Use + # <tt>Model.find(:all, *args)</tt> or its shortcut <tt>Model.all(*args)</tt>. + # + # All approaches accept an options hash as their last parameter. + # + # ==== Attributes + # + # * <tt>:conditions</tt> - An SQL fragment like "administrator = 1" or <tt>[ "user_name = ?", username ]</tt>. See conditions in the intro. + # * <tt>:order</tt> - An SQL fragment like "created_at DESC, name". + # * <tt>:group</tt> - An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause. + # * <tt>:limit</tt> - An integer determining the limit on the number of rows that should be returned. + # * <tt>:offset</tt> - An integer determining the offset from where the rows should be fetched. So at 5, it would skip rows 0 through 4. + # * <tt>:joins</tt> - Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed) + # or named associations in the same form used for the <tt>:include</tt> option, which will perform an <tt>INNER JOIN</tt> on the associated table(s). # If the value is a string, then the records will be returned read-only since they will have attributes that do not correspond to the table's columns. # Pass <tt>:readonly => false</tt> to override. - # * <tt>:include</tt>: Names associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer + # * <tt>:include</tt> - Names associations that should be loaded alongside. The symbols named refer # to already defined associations. See eager loading under Associations. - # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join but not + # * <tt>:select</tt> - By default, this is "*" as in "SELECT * FROM", but can be changed if you, for example, want to do a join but not # include the joined columns. - # * <tt>:from</tt>: By default, this is the table name of the class, but can be changed to an alternate table name (or even the name + # * <tt>:from</tt> - By default, this is the table name of the class, but can be changed to an alternate table name (or even the name # of a database view). - # * <tt>:readonly</tt>: Mark the returned records read-only so they cannot be saved or updated. - # * <tt>:lock</tt>: An SQL fragment like "FOR UPDATE" or "LOCK IN SHARE MODE". + # * <tt>:readonly</tt> - Mark the returned records read-only so they cannot be saved or updated. + # * <tt>:lock</tt> - An SQL fragment like "FOR UPDATE" or "LOCK IN SHARE MODE". # <tt>:lock => true</tt> gives connection's default exclusive lock, usually "FOR UPDATE". # - # Examples for find by id: + # ==== Examples + # + # # find by id # Person.find(1) # returns the object for ID = 1 # Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6) # Person.find([7, 17]) # returns an array for objects with IDs in (7, 17) @@ -486,17 +494,19 @@ module ActiveRecord #:nodoc: # provide since database rows are unordered. Give an explicit <tt>:order</tt> # to ensure the results are sorted. # - # Examples for find first: + # ==== Examples + # + # # find first # Person.find(:first) # returns the first object fetched by SELECT * FROM people # Person.find(:first, :conditions => [ "user_name = ?", user_name]) # Person.find(:first, :order => "created_on DESC", :offset => 5) # - # Examples for find last: + # # find last # Person.find(:last) # returns the last object fetched by SELECT * FROM people # Person.find(:last, :conditions => [ "user_name = ?", user_name]) # Person.find(:last, :order => "created_on DESC", :offset => 5) # - # Examples for find all: + # # find all # Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people # Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50) # Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] } @@ -504,11 +514,12 @@ module ActiveRecord #:nodoc: # Person.find(:all, :include => [ :account, :friends ]) # Person.find(:all, :group => "category") # - # Example for find with a lock. Imagine two concurrent transactions: - # each will read person.visits == 2, add 1 to it, and save, resulting - # in two saves of person.visits = 3. By locking the row, the second + # Example for find with a lock: Imagine two concurrent transactions: + # each will read <tt>person.visits == 2</tt>, add 1 to it, and save, resulting + # in two saves of <tt>person.visits = 3</tt>. By locking the row, the second # transaction has to wait until the first is finished; we get the - # expected person.visits == 4. + # expected <tt>person.visits == 4</tt>. + # # Person.transaction do # person = Person.find(1, :lock => true) # person.visits += 1 @@ -527,14 +538,14 @@ module ActiveRecord #:nodoc: end end - # This is an alias for find(:first). You can pass in all the same arguments to this method as you can - # to find(:first) + # A convenience wrapper for <tt>find(:first, *args)</tt>. You can pass in all the + # same arguments to this method as you can to <tt>find(:first)</tt>. def first(*args) find(:first, *args) end - # This is an alias for find(:last). You can pass in all the same arguments to this method as you can - # to find(:last) + # A convenience wrapper for <tt>find(:last, *args)</tt>. You can pass in all the + # same arguments to this method as you can to <tt>find(:last)</tt>. def last(*args) find(:last, *args) end @@ -545,8 +556,7 @@ module ActiveRecord #:nodoc: find(:all, *args) end - # - # Executes a custom sql query against your database and returns all the results. The results will + # Executes a custom SQL query against your database and returns all the results. The results will # be returned as an array with columns requested encapsulated as attributes of the model you call # this method from. If you call +Product.find_by_sql+ then the results will be returned in a Product # object with the attributes you specified in the SQL query. @@ -555,13 +565,13 @@ module ActiveRecord #:nodoc: # SELECT will be attributes of the model, whether or not they are columns of the corresponding # table. # - # The +sql+ parameter is a full sql query as a string. It will be called as is, there will be + # The +sql+ parameter is a full SQL query as a string. It will be called as is, there will be # no database agnostic conversions performed. This should be a last resort because using, for example, # MySQL specific terms will lock you to using that particular database engine or require you to # change your call if you switch engines # # ==== Examples - # # A simple sql query spanning multiple tables + # # A simple SQL query spanning multiple tables # Post.find_by_sql "SELECT p.title, c.author FROM posts p, comments c WHERE p.id = c.post_id" # > [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...] # @@ -860,9 +870,15 @@ module ActiveRecord #:nodoc: end - # Attributes named in this macro are protected from mass-assignment, such as <tt>new(attributes)</tt> and - # <tt>attributes=(attributes)</tt>. Their assignment will simply be ignored. Instead, you can use the direct writer - # methods to do assignment. This is meant to protect sensitive attributes from being overwritten by URL/form hackers. Example: + # Attributes named in this macro are protected from mass-assignment, + # such as <tt>new(attributes)</tt>, + # <tt>update_attributes(attributes)</tt>, or + # <tt>attributes=(attributes)</tt>. + # + # Mass-assignment to these attributes will simply be ignored, to assign + # to them you can use direct writer methods. This is meant to protect + # sensitive attributes from being overwritten by malicious users + # tampering with URLs or forms. # # class Customer < ActiveRecord::Base # attr_protected :credit_rating @@ -876,7 +892,8 @@ module ActiveRecord #:nodoc: # customer.credit_rating = "Average" # customer.credit_rating # => "Average" # - # To start from an all-closed default and enable attributes as needed, have a look at attr_accessible. + # To start from an all-closed default and enable attributes as needed, + # have a look at +attr_accessible+. def attr_protected(*attributes) write_inheritable_attribute("attr_protected", Set.new(attributes.map(&:to_s)) + (protected_attributes || [])) end @@ -886,19 +903,18 @@ module ActiveRecord #:nodoc: read_inheritable_attribute("attr_protected") end - # Similar to the attr_protected macro, this protects attributes of your model from mass-assignment, - # such as <tt>new(attributes)</tt> and <tt>attributes=(attributes)</tt> - # however, it does it in the opposite way. This locks all attributes and only allows access to the - # attributes specified. Assignment to attributes not in this list will be ignored and need to be set - # using the direct writer methods instead. This is meant to protect sensitive attributes from being - # overwritten by URL/form hackers. If you'd rather start from an all-open default and restrict - # attributes as needed, have a look at attr_protected. - # - # ==== Attributes - # - # * <tt>*attributes</tt> A comma separated list of symbols that represent columns _not_ to be protected + # Specifies a white list of model attributes that can be set via + # mass-assignment, such as <tt>new(attributes)</tt>, + # <tt>update_attributes(attributes)</tt>, or + # <tt>attributes=(attributes)</tt> # - # ==== Examples + # This is the opposite of the +attr_protected+ macro: Mass-assignment + # will only set attributes in this list, to assign to the rest of + # attributes you can use direct writer methods. This is meant to protect + # sensitive attributes from being overwritten by malicious users + # tampering with URLs or forms. If you'd rather start from an all-open + # default and restrict attributes as needed, have a look at + # +attr_protected+. # # class Customer < ActiveRecord::Base # attr_accessible :name, :nickname @@ -933,7 +949,7 @@ module ActiveRecord #:nodoc: # If you have an attribute that needs to be saved to the database as an object, and retrieved as the same object, # then specify the name of that attribute using this method and it will be handled automatically. # The serialization is done through YAML. If +class_name+ is specified, the serialized object must be of that - # class on retrieval or +SerializationTypeMismatch+ will be raised. + # class on retrieval or SerializationTypeMismatch will be raised. # # ==== Attributes # @@ -956,12 +972,14 @@ module ActiveRecord #:nodoc: # Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending - # directly from ActiveRecord. So if the hierarchy looks like: Reply < Message < ActiveRecord, then Message is used + # directly from ActiveRecord::Base. So if the hierarchy looks like: Reply < Message < ActiveRecord::Base, then Message is used # to guess the table name even when called on Reply. The rules used to do the guess are handled by the Inflector class # in Active Support, which knows almost all common English inflections. You can add new inflections in config/initializers/inflections.rb. # # Nested classes are given table names prefixed by the singular form of - # the parent's table name. Enclosing modules are not considered. Examples: + # the parent's table name. Enclosing modules are not considered. + # + # ==== Examples # # class Invoice < ActiveRecord::Base; end; # file class table_name @@ -975,8 +993,8 @@ module ActiveRecord #:nodoc: # file class table_name # invoice/lineitem.rb Invoice::Lineitem lineitems # - # Additionally, the class-level table_name_prefix is prepended and the - # table_name_suffix is appended. So if you have "myapp_" as a prefix, + # Additionally, the class-level +table_name_prefix+ is prepended and the + # +table_name_suffix+ is appended. So if you have "myapp_" as a prefix, # the table name guess for an Invoice class becomes "myapp_invoices". # Invoice::Lineitem becomes "myapp_invoice_lineitems". # @@ -1055,8 +1073,6 @@ module ActiveRecord #:nodoc: # Sets the table name to use to the given value, or (if the value # is nil or false) to the value returned by the given block. # - # Example: - # # class Project < ActiveRecord::Base # set_table_name "project" # end @@ -1069,8 +1085,6 @@ module ActiveRecord #:nodoc: # or (if the value is nil or false) to the value returned by the given # block. # - # Example: - # # class Project < ActiveRecord::Base # set_primary_key "sysid" # end @@ -1083,8 +1097,6 @@ module ActiveRecord #:nodoc: # or (if the value # is nil or false) to the value returned by the # given block. # - # Example: - # # class Project < ActiveRecord::Base # set_inheritance_column do # original_inheritance_column + "_id" @@ -1106,8 +1118,6 @@ module ActiveRecord #:nodoc: # If a sequence name is not explicitly set when using PostgreSQL, it # will discover the sequence corresponding to your primary key for you. # - # Example: - # # class Project < ActiveRecord::Base # set_sequence_name "projectseq" # default would have been "project_seq" # end @@ -1267,7 +1277,7 @@ module ActiveRecord #:nodoc: class_of_active_record_descendant(self) end - # Set this to true if this is an abstract class (see #abstract_class?). + # Set this to true if this is an abstract class (see <tt>abstract_class?</tt>). attr_accessor :abstract_class # Returns whether this class is a base AR class. If A is a base class and @@ -1714,8 +1724,8 @@ module ActiveRecord #:nodoc: end - # Defines an "attribute" method (like #inheritance_column or - # #table_name). A new (class) method will be created with the + # Defines an "attribute" method (like +inheritance_column+ or + # +table_name+). A new (class) method will be created with the # given name. If a value is specified, the new method will # return that value (as a string). Otherwise, the given block # will be used to compute the value of the method. @@ -1892,7 +1902,7 @@ module ActiveRecord #:nodoc: end end - # Returns the class descending directly from ActiveRecord in the inheritance hierarchy. + # Returns the class descending directly from Active Record in the inheritance hierarchy. def class_of_active_record_descendant(klass) if klass.superclass == Base || klass.superclass.abstract_class? klass @@ -1903,12 +1913,12 @@ module ActiveRecord #:nodoc: end end - # Returns the name of the class descending directly from ActiveRecord in the inheritance hierarchy. + # Returns the name of the class descending directly from Active Record in the inheritance hierarchy. def class_name_of_active_record_descendant(klass) #:nodoc: klass.base_class.name end - # Accepts an array, hash, or string of sql conditions and sanitizes + # Accepts an array, hash, or string of SQL conditions and sanitizes # them into a valid SQL fragment for a WHERE clause. # ["name='%s' and group_id='%s'", "foo'bar", 4] returns "name='foo''bar' and group_id='4'" # { :name => "foo'bar", :group_id => 4 } returns "name='foo''bar' and group_id='4'" @@ -1924,7 +1934,7 @@ module ActiveRecord #:nodoc: end alias_method :sanitize_sql, :sanitize_sql_for_conditions - # Accepts an array, hash, or string of sql conditions and sanitizes + # Accepts an array, hash, or string of SQL conditions and sanitizes # them into a valid SQL fragment for a SET clause. # { :name => nil, :group_id => 4 } returns "name = NULL , group_id='4'" def sanitize_sql_for_assignment(assignments) @@ -1940,7 +1950,7 @@ module ActiveRecord #:nodoc: mapping.first.is_a?(Array) ? mapping : [mapping] end - # Accepts a hash of sql conditions and replaces those attributes + # Accepts a hash of SQL conditions and replaces those attributes # that correspond to a +composed_of+ relationship with their expanded # aggregate attribute values. # Given: @@ -2013,7 +2023,7 @@ module ActiveRecord #:nodoc: end # Accepts an array of conditions. The array has each value - # sanitized and interpolated into the sql statement. + # sanitized and interpolated into the SQL statement. # ["name='%s' and group_id='%s'", "foo'bar", 4] returns "name='foo''bar' and group_id='4'" def sanitize_sql_array(ary) statement, *values = ary @@ -2134,7 +2144,9 @@ module ActiveRecord #:nodoc: (id = self.id) ? id.to_s : nil # Be sure to stringify the id for routes end - # Returns a cache key that can be used to identify this record. Examples: + # Returns a cache key that can be used to identify this record. + # + # ==== Examples # # Product.new.cache_key # => "products/new" # Product.find(5).cache_key # => "products/5" (updated_at not available) @@ -2490,9 +2502,9 @@ module ActiveRecord #:nodoc: id end - # Sets the attribute used for single table inheritance to this class name if this is not the ActiveRecord descendent. - # Considering the hierarchy Reply < Message < ActiveRecord, this makes it possible to do Reply.new without having to - # set Reply[Reply.inheritance_column] = "Reply" yourself. No such attribute would be set for objects of the + # Sets the attribute used for single table inheritance to this class name if this is not the ActiveRecord::Base descendent. + # Considering the hierarchy Reply < Message < ActiveRecord::Base, this makes it possible to do Reply.new without having to + # set <tt>Reply[Reply.inheritance_column] = "Reply"</tt> yourself. No such attribute would be set for objects of the # Message class in that example. def ensure_proper_type unless self.class.descends_from_active_record? @@ -2564,7 +2576,7 @@ module ActiveRecord #:nodoc: self.class.connection.quote(value, column) end - # Interpolate custom sql string in instance context. + # Interpolate custom SQL string in instance context. # Optional record argument is meant for custom insert_sql. def interpolate_sql(sql, record = nil) instance_eval("%@#{sql.gsub('@', '\@')}@") diff --git a/activerecord/lib/active_record/calculations.rb b/activerecord/lib/active_record/calculations.rb index 3c5caefe3b..10e8330d1c 100644 --- a/activerecord/lib/active_record/calculations.rb +++ b/activerecord/lib/active_record/calculations.rb @@ -46,28 +46,28 @@ module ActiveRecord calculate(:count, *construct_count_options_from_args(*args)) end - # Calculates the average value on a given column. The value is returned as a float. See #calculate for examples with options. + # Calculates the average value on a given column. The value is returned as a float. See +calculate+ for examples with options. # # Person.average('age') def average(column_name, options = {}) calculate(:avg, column_name, options) end - # Calculates the minimum value on a given column. The value is returned with the same data type of the column. See #calculate for examples with options. + # Calculates the minimum value on a given column. The value is returned with the same data type of the column. See +calculate+ for examples with options. # # Person.minimum('age') def minimum(column_name, options = {}) calculate(:min, column_name, options) end - # Calculates the maximum value on a given column. The value is returned with the same data type of the column. See #calculate for examples with options. + # Calculates the maximum value on a given column. The value is returned with the same data type of the column. See +calculate+ for examples with options. # # Person.maximum('age') def maximum(column_name, options = {}) calculate(:max, column_name, options) end - # Calculates the sum of values on a given column. The value is returned with the same data type of the column. See #calculate for examples with options. + # Calculates the sum of values on a given column. The value is returned with the same data type of the column. See +calculate+ for examples with options. # # Person.sum('age') def sum(column_name, options = {}) @@ -245,12 +245,14 @@ module ActiveRecord options.assert_valid_keys(CALCULATIONS_OPTIONS) end - # Converts a given key to the value that the database adapter returns as - # a usable column name. - # users.id #=> users_id - # sum(id) #=> sum_id - # count(distinct users.id) #=> count_distinct_users_id - # count(*) #=> count_all + # Converts the given keys to the value that the database adapter returns as + # a usable column name: + # + # column_alias_for("users.id") # => "users_id" + # column_alias_for("sum(id)") # => "sum_id" + # column_alias_for("count(distinct users.id)") # => "count_distinct_users_id" + # column_alias_for("count(*)") # => "count_all" + # column_alias_for("count", "id") # => "count_id" def column_alias_for(*keys) connection.table_alias_for(keys.join(' ').downcase.gsub(/\*/, 'all').gsub(/\W+/, ' ').strip.gsub(/ +/, '_')) end diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb index a469af682b..41ec5c5e61 100755 --- a/activerecord/lib/active_record/callbacks.rb +++ b/activerecord/lib/active_record/callbacks.rb @@ -161,7 +161,7 @@ module ActiveRecord # == <tt>before_validation*</tt> returning statements # # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+. - # If <tt>Base#save!</tt> is called it will raise a +RecordNotSaved+ exception. + # If Base#save! is called it will raise a RecordNotSaved exception. # Nothing will be appended to the errors object. # # == Canceling callbacks diff --git a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb index 34627dfaf9..2a8807fb78 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb @@ -193,7 +193,7 @@ module ActiveRecord # :database => "path/to/dbfile" # ) # - # Also accepts keys as strings (for parsing from yaml for example): + # Also accepts keys as strings (for parsing from YAML for example): # # ActiveRecord::Base.establish_connection( # "adapter" => "sqlite", diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb index 589acd3945..16d405d3bd 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb @@ -29,7 +29,7 @@ module ActiveRecord end # Returns an array of arrays containing the field values. - # Order is the same as that returned by #columns. + # Order is the same as that returned by +columns+. def select_rows(sql, name = nil) raise NotImplementedError, "select_rows is an abstract method" end @@ -93,7 +93,7 @@ module ActiveRecord # done if the transaction block raises an exception or returns false. def rollback_db_transaction() end - # Alias for #add_limit_offset!. + # Alias for <tt>add_limit_offset!</tt>. def add_limit!(sql, options) add_limit_offset!(sql, options) if options end diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb index fdb18b234c..f968b9b173 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb @@ -16,9 +16,9 @@ module ActiveRecord # Instantiates a new column in the table. # - # +name+ is the column's name, as in <tt><b>supplier_id</b> int(11)</tt>. - # +default+ is the type-casted default value, such as <tt>sales_stage varchar(20) default <b>'new'</b></tt>. - # +sql_type+ is only used to extract the column's length, if necessary. For example, <tt>company_name varchar(<b>60</b>)</tt>. + # +name+ is the column's name, such as <tt>supplier_id</tt> in <tt>supplier_id int(11)</tt>. + # +default+ is the type-casted default value, such as +new+ in <tt>sales_stage varchar(20) default 'new'</tt>. + # +sql_type+ is only used to extract the column's length, if necessary. For example +60+ in <tt>company_name varchar(60)</tt>. # +null+ determines if this column allows +NULL+ values. def initialize(name, default, sql_type = nil, null = true) @name, @sql_type, @null = name, sql_type, null @@ -92,7 +92,7 @@ module ActiveRecord # Returns the human name of the column name. # # ===== Examples - # Column.new('sales_stage', ...).human_name #=> 'Sales stage' + # Column.new('sales_stage', ...).human_name # => 'Sales stage' def human_name Base.human_attribute_name(@name) end @@ -270,7 +270,7 @@ module ActiveRecord end # Represents a SQL table in an abstract way. - # Columns are stored as a ColumnDefinition in the #columns attribute. + # Columns are stored as a ColumnDefinition in the +columns+ attribute. class TableDefinition attr_accessor :columns @@ -350,28 +350,28 @@ module ActiveRecord # == Examples # # Assuming td is an instance of TableDefinition # td.column(:granted, :boolean) - # #=> granted BOOLEAN + # # granted BOOLEAN # # td.column(:picture, :binary, :limit => 2.megabytes) - # #=> picture BLOB(2097152) + # # => picture BLOB(2097152) # # td.column(:sales_stage, :string, :limit => 20, :default => 'new', :null => false) - # #=> sales_stage VARCHAR(20) DEFAULT 'new' NOT NULL + # # => sales_stage VARCHAR(20) DEFAULT 'new' NOT NULL # - # def.column(:bill_gates_money, :decimal, :precision => 15, :scale => 2) - # #=> bill_gates_money DECIMAL(15,2) + # td.column(:bill_gates_money, :decimal, :precision => 15, :scale => 2) + # # => bill_gates_money DECIMAL(15,2) # - # def.column(:sensor_reading, :decimal, :precision => 30, :scale => 20) - # #=> sensor_reading DECIMAL(30,20) + # td.column(:sensor_reading, :decimal, :precision => 30, :scale => 20) + # # => sensor_reading DECIMAL(30,20) # # # While <tt>:scale</tt> defaults to zero on most databases, it # # probably wouldn't hurt to include it. - # def.column(:huge_integer, :decimal, :precision => 30) - # #=> huge_integer DECIMAL(30) + # td.column(:huge_integer, :decimal, :precision => 30) + # # => huge_integer DECIMAL(30) # # == Short-hand examples # - # Instead of calling column directly, you can also work with the short-hand definitions for the default types. + # Instead of calling +column+ directly, you can also work with the short-hand definitions for the default types. # They use the type as the method name instead of as a parameter and allow for multiple columns to be defined # in a single statement. # @@ -395,7 +395,7 @@ module ActiveRecord # end # # There's a short-hand method for each of the type values declared at the top. And then there's - # TableDefinition#timestamps that'll add created_at and updated_at as datetimes. + # TableDefinition#timestamps that'll add created_at and +updated_at+ as datetimes. # # TableDefinition#references will add an appropriately-named _id column, plus a corresponding _type # column if the <tt>:polymorphic</tt> option is supplied. If <tt>:polymorphic</tt> is a hash of options, these will be diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index b57d0a3ef7..67d70b3886 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -32,7 +32,7 @@ module ActiveRecord def columns(table_name, name = nil) end # Creates a new table - # There are two ways to work with #create_table. You can use the block + # There are two ways to work with +create_table+. You can use the block # form or the regular form, like this: # # === Block form diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb index 2ec2d80af4..7dbfbb41f6 100644 --- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb @@ -776,7 +776,7 @@ module ActiveRecord # Returns an ORDER BY clause for the passed order option. # # PostgreSQL does not allow arbitrary ordering when using DISTINCT ON, so we work around this - # by wrapping the sql as a sub-select and ordering in that query. + # by wrapping the +sql+ string as a sub-select and ordering in that query. def add_order_by_for_association_limiting!(sql, options) #:nodoc: return sql if options[:order].blank? diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb index ac06cdbe43..c4cbe5d52f 100755 --- a/activerecord/lib/active_record/fixtures.rb +++ b/activerecord/lib/active_record/fixtures.rb @@ -33,8 +33,8 @@ end # # Unlike single-file fixtures, YAML fixtures are stored in a single file per model, which are placed in the directory appointed # by <tt>ActiveSupport::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just -# put your files in <your-rails-app>/test/fixtures/). The fixture file ends with the .yml file extension (Rails example: -# "<your-rails-app>/test/fixtures/web_sites.yml"). The format of a YAML fixture file looks like this: +# put your files in <tt><your-rails-app>/test/fixtures/</tt>). The fixture file ends with the <tt>.yml</tt> file extension (Rails example: +# <tt><your-rails-app>/test/fixtures/web_sites.yml</tt>). The format of a YAML fixture file looks like this: # # rubyonrails: # id: 1 @@ -67,7 +67,8 @@ end # = CSV fixtures # # Fixtures can also be kept in the Comma Separated Value format. Akin to YAML fixtures, CSV fixtures are stored -# in a single file, but instead end with the .csv file extension (Rails example: "<your-rails-app>/test/fixtures/web_sites.csv") +# in a single file, but instead end with the <tt>.csv</tt> file extension +# (Rails example: <tt><your-rails-app>/test/fixtures/web_sites.csv</tt>). # # The format of this type of fixture file is much more compact than the others, but also a little harder to read by us # humans. The first line of the CSV file is a comma-separated list of field names. The rest of the file is then comprised @@ -93,11 +94,11 @@ end # This type of fixture was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats. # Fixtures for this format are created by placing text files in a sub-directory (with the name of the model) to the directory # appointed by <tt>ActiveSupport::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just -# put your files in <your-rails-app>/test/fixtures/<your-model-name>/ -- like <your-rails-app>/test/fixtures/web_sites/ for the WebSite -# model). +# put your files in <tt><your-rails-app>/test/fixtures/<your-model-name>/</tt> -- +# like <tt><your-rails-app>/test/fixtures/web_sites/</tt> for the WebSite model). # # Each text file placed in this directory represents a "record". Usually these types of fixtures are named without -# extensions, but if you are on a Windows machine, you might consider adding .txt as the extension. Here's what the +# extensions, but if you are on a Windows machine, you might consider adding <tt>.txt</tt> as the extension. Here's what the # above example might look like: # # web_sites/google @@ -138,20 +139,20 @@ end # # In addition to being available in the database, the fixtures are also loaded into a hash stored in an instance variable # of the test case. It is named after the symbol... so, in our example, there would be a hash available called -# @web_sites. This is where the "fixture name" comes into play. +# <tt>@web_sites</tt>. This is where the "fixture name" comes into play. # -# On top of that, each record is automatically "found" (using Model.find(id)) and placed in the instance variable of its name. -# So for the YAML fixtures, we'd get @rubyonrails and @google, which could be interrogated using regular Active Record semantics: +# On top of that, each record is automatically "found" (using <tt>Model.find(id)</tt>) and placed in the instance variable of its name. +# So for the YAML fixtures, we'd get <tt>@rubyonrails</tt> and <tt>@google</tt>, which could be interrogated using regular Active Record semantics: # # # test if the object created from the fixture data has the same attributes as the data itself # def test_find # assert_equal @web_sites["rubyonrails"]["name"], @rubyonrails.name # end # -# As seen above, the data hash created from the YAML fixtures would have @web_sites["rubyonrails"]["url"] return -# "http://www.rubyonrails.org" and @web_sites["google"]["name"] would return "Google". The same fixtures, but loaded -# from a CSV fixture file, would be accessible via @web_sites["web_site_1"]["name"] == "Ruby on Rails" and have the individual -# fixtures available as instance variables @web_site_1 and @web_site_2. +# As seen above, the data hash created from the YAML fixtures would have <tt>@web_sites["rubyonrails"]["url"]</tt> return +# "http://www.rubyonrails.org" and <tt>@web_sites["google"]["name"]</tt> would return "Google". The same fixtures, but loaded +# from a CSV fixture file, would be accessible via <tt>@web_sites["web_site_1"]["name"] == "Ruby on Rails"</tt> and have the individual +# fixtures available as instance variables <tt>@web_site_1</tt> and <tt>@web_site_2</tt>. # # If you do not wish to use instantiated fixtures (usually for performance reasons) there are two options. # @@ -184,7 +185,7 @@ end # # This will create 1000 very simple YAML fixtures. # -# Using ERb, you can also inject dynamic values into your fixtures with inserts like <%= Date.today.strftime("%Y-%m-%d") %>. +# Using ERb, you can also inject dynamic values into your fixtures with inserts like <tt><%= Date.today.strftime("%Y-%m-%d") %></tt>. # This is however a feature to be used with some caution. The point of fixtures are that they're stable units of predictable # sample data. If you feel that you need to inject dynamic values, then perhaps you should reexamine whether your application # is properly testable. Hence, dynamic values in fixtures are to be considered a code smell. @@ -257,7 +258,7 @@ end # reginald: # generated id: 324201669 # name: Reginald the Pirate # -# ActiveRecord looks at the fixture's model class, discovers the correct +# Active Record looks at the fixture's model class, discovers the correct # primary key, and generates it right before inserting the fixture # into the database. # @@ -267,7 +268,7 @@ end # == Label references for associations (belongs_to, has_one, has_many) # # Specifying foreign keys in fixtures can be very fragile, not to -# mention difficult to read. Since ActiveRecord can figure out the ID of +# mention difficult to read. Since Active Record can figure out the ID of # any fixture from its label, you can specify FK's by label instead of ID. # # === belongs_to @@ -304,15 +305,15 @@ end # name: George the Monkey # pirate: reginald # -# Pow! All is made clear. ActiveRecord reflects on the fixture's model class, +# Pow! All is made clear. Active Record reflects on the fixture's model class, # finds all the +belongs_to+ associations, and allows you to specify # a target *label* for the *association* (monkey: george) rather than -# a target *id* for the *FK* (monkey_id: 1). +# a target *id* for the *FK* (<tt>monkey_id: 1</tt>). # # ==== Polymorphic belongs_to # # Supporting polymorphic relationships is a little bit more complicated, since -# ActiveRecord needs to know what type your association is pointing at. Something +# Active Record needs to know what type your association is pointing at. Something # like this should look familiar: # # ### in fruit.rb @@ -332,7 +333,7 @@ end # apple: # eater: george (Monkey) # -# Just provide the polymorphic target type and ActiveRecord will take care of the rest. +# Just provide the polymorphic target type and Active Record will take care of the rest. # # === has_and_belongs_to_many # @@ -395,15 +396,15 @@ end # # Zap! No more fruits_monkeys.yml file. We've specified the list of fruits # on George's fixture, but we could've just as easily specified a list -# of monkeys on each fruit. As with +belongs_to+, ActiveRecord reflects on +# of monkeys on each fruit. As with +belongs_to+, Active Record reflects on # the fixture's model class and discovers the +has_and_belongs_to_many+ # associations. # # == Autofilled timestamp columns # -# If your table/model specifies any of ActiveRecord's -# standard timestamp columns (created_at, created_on, updated_at, updated_on), -# they will automatically be set to Time.now. +# If your table/model specifies any of Active Record's +# standard timestamp columns (+created_at+, +created_on+, +updated_at+, +updated_on+), +# they will automatically be set to <tt>Time.now</tt>. # # If you've set specific values, they'll be left alone. # diff --git a/activerecord/lib/active_record/locking/optimistic.rb b/activerecord/lib/active_record/locking/optimistic.rb index 65f88cfdc7..c66034d18b 100644 --- a/activerecord/lib/active_record/locking/optimistic.rb +++ b/activerecord/lib/active_record/locking/optimistic.rb @@ -107,20 +107,20 @@ module ActiveRecord end # Is optimistic locking enabled for this table? Returns true if the - # #lock_optimistically flag is set to true (which it is, by default) - # and the table includes the #locking_column column (defaults to - # lock_version). + # +lock_optimistically+ flag is set to true (which it is, by default) + # and the table includes the +locking_column+ column (defaults to + # +lock_version+). def locking_enabled? lock_optimistically && columns_hash[locking_column] end - # Set the column to use for optimistic locking. Defaults to lock_version. + # Set the column to use for optimistic locking. Defaults to +lock_version+. def set_locking_column(value = nil, &block) define_attr_method :locking_column, value, &block value end - # The version column used for optimistic locking. Defaults to lock_version. + # The version column used for optimistic locking. Defaults to +lock_version+. def locking_column reset_locking_column end @@ -130,12 +130,12 @@ module ActiveRecord connection.quote_column_name(locking_column) end - # Reset the column used for optimistic locking back to the lock_version default. + # Reset the column used for optimistic locking back to the +lock_version+ default. def reset_locking_column set_locking_column DEFAULT_LOCKING_COLUMN end - # make sure the lock version column gets updated when counters are + # Make sure the lock version column gets updated when counters are # updated. def update_counters_with_lock(id, counters) counters = counters.merge(locking_column => 1) if locking_enabled? diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb index 5cc9f4e197..b47b01e99a 100644 --- a/activerecord/lib/active_record/migration.rb +++ b/activerecord/lib/active_record/migration.rb @@ -208,7 +208,7 @@ module ActiveRecord # # You can quiet them down by setting ActiveRecord::Migration.verbose = false. # - # You can also insert your own messages and benchmarks by using the #say_with_time + # You can also insert your own messages and benchmarks by using the +say_with_time+ # method: # # def self.up @@ -377,7 +377,7 @@ module ActiveRecord end def proper_table_name(name) - # Use the ActiveRecord objects own table_name, or pre/suffix from ActiveRecord::Base if name is a symbol/string + # Use the Active Record objects own table_name, or pre/suffix from ActiveRecord::Base if name is a symbol/string name.table_name rescue "#{ActiveRecord::Base.table_name_prefix}#{name}#{ActiveRecord::Base.table_name_suffix}" end end diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index c7cf1731c1..69b7da7700 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -2,9 +2,7 @@ module ActiveRecord module NamedScope # All subclasses of ActiveRecord::Base have two named_scopes: # * <tt>all</tt>, which is similar to a <tt>find(:all)</tt> query, and - # * <tt>scoped</tt>, which allows for the creation of anonymous scopes, on the fly: - # - # Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions) + # * <tt>scoped</tt>, which allows for the creation of anonymous scopes, on the fly: <tt>Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)</tt> # # These anonymous scopes tend to be useful when procedurally generating complex queries, where passing # intermediate values (scopes) around as first-class objects is convenient. @@ -41,7 +39,7 @@ module ActiveRecord # Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments # for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>. # - # All scopes are available as class methods on the ActiveRecord descendent upon which the scopes were defined. But they are also available to + # All scopes are available as class methods on the ActiveRecord::Base descendent upon which the scopes were defined. But they are also available to # <tt>has_many</tt> associations. If, # # class Person < ActiveRecord::Base diff --git a/activerecord/lib/active_record/observer.rb b/activerecord/lib/active_record/observer.rb index 2b0728fc25..6e55e36b7d 100644 --- a/activerecord/lib/active_record/observer.rb +++ b/activerecord/lib/active_record/observer.rb @@ -19,7 +19,7 @@ module ActiveRecord # # Same as above, just using explicit class references # ActiveRecord::Base.observers = Cacher, GarbageCollector # - # Note: Setting this does not instantiate the observers yet. #instantiate_observers is + # Note: Setting this does not instantiate the observers yet. +instantiate_observers+ is # called during startup, and before each development request. def observers=(*observers) @observers = observers.flatten @@ -30,7 +30,7 @@ module ActiveRecord @observers ||= [] end - # Instantiate the global ActiveRecord observers + # Instantiate the global Active Record observers. def instantiate_observers return if @observers.blank? @observers.each do |observer| diff --git a/activerecord/lib/active_record/schema.rb b/activerecord/lib/active_record/schema.rb index d6b254fcf9..8a32cf1ca2 100644 --- a/activerecord/lib/active_record/schema.rb +++ b/activerecord/lib/active_record/schema.rb @@ -30,8 +30,8 @@ module ActiveRecord # Eval the given block. All methods available to the current connection # adapter are available within the block, so you can easily use the - # database definition DSL to build up your schema (#create_table, - # #add_index, etc.). + # database definition DSL to build up your schema (+create_table+, + # +add_index+, etc.). # # The +info+ hash is optional, and if given is used to define metadata # about the current schema (currently, only the schema's version): diff --git a/activerecord/lib/active_record/schema_dumper.rb b/activerecord/lib/active_record/schema_dumper.rb index 826662d3ee..b90ed88c6b 100644 --- a/activerecord/lib/active_record/schema_dumper.rb +++ b/activerecord/lib/active_record/schema_dumper.rb @@ -38,7 +38,7 @@ module ActiveRecord stream.puts <<HEADER # This file is auto-generated from the current state of the database. Instead of editing this file, -# please use the migrations feature of ActiveRecord to incrementally modify your database, and +# please use the migrations feature of Active Record to incrementally modify your database, and # then regenerate this schema definition. # # Note that this schema.rb definition is the authoritative source for your database schema. If you need diff --git a/activerecord/lib/active_record/serializers/xml_serializer.rb b/activerecord/lib/active_record/serializers/xml_serializer.rb index 2d0887ecf0..d171b742f5 100644 --- a/activerecord/lib/active_record/serializers/xml_serializer.rb +++ b/activerecord/lib/active_record/serializers/xml_serializer.rb @@ -273,14 +273,14 @@ module ActiveRecord #:nodoc: end # There is a significant speed improvement if the value - # does not need to be escaped, as #tag! escapes all values + # does not need to be escaped, as <tt>tag!</tt> escapes all values # to ensure that valid XML is generated. For known binary # values, it is at least an order of magnitude faster to # Base64 encode binary values and directly put them in the # output XML than to pass the original value or the Base64 - # encoded value to the #tag! method. It definitely makes + # encoded value to the <tt>tag!</tt> method. It definitely makes # no sense to Base64 encode the value and then give it to - # #tag!, since that just adds additional overhead. + # <tt>tag!</tt>, since that just adds additional overhead. def needs_encoding? ![ :binary, :date, :datetime, :boolean, :float, :integer ].include?(type) end diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb index 13cb5f3f48..3b6835762c 100644 --- a/activerecord/lib/active_record/transactions.rb +++ b/activerecord/lib/active_record/transactions.rb @@ -30,9 +30,9 @@ module ActiveRecord # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though, # that the objects will _not_ have their instance data returned to their pre-transactional state. # - # == Different ActiveRecord classes in a single transaction + # == Different Active Record classes in a single transaction # - # Though the transaction class method is called on some ActiveRecord class, + # Though the transaction class method is called on some Active Record class, # the objects within the transaction block need not all be instances of # that class. # In this example a <tt>Balance</tt> record is transactionally saved even diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index b3a75121ed..0e150bddb2 100755 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -301,7 +301,7 @@ module ActiveRecord :odd => 'odd?', :even => 'even?' }.freeze # Adds a validation method or block to the class. This is useful when - # overriding the #validate instance method becomes too unwieldly and + # overriding the +validate+ instance method becomes too unwieldly and # you're looking for more descriptive declaration of your validations. # # This can be done with a symbol pointing to a method: @@ -326,7 +326,7 @@ module ActiveRecord # end # end # - # This usage applies to #validate_on_create and #validate_on_update as well. + # This usage applies to +validate_on_create+ and +validate_on_update+ as well. # Validates each attribute against a block. # diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb index 08fd0123f6..463ee9f1e7 100644 --- a/activeresource/lib/active_resource/base.rb +++ b/activeresource/lib/active_resource/base.rb @@ -34,18 +34,18 @@ module ActiveResource # from REST web services. # # ryan = Person.new(:first => 'Ryan', :last => 'Daigle') - # ryan.save #=> true - # ryan.id #=> 2 - # Person.exists?(ryan.id) #=> true - # ryan.exists? #=> true + # ryan.save # => true + # ryan.id # => 2 + # Person.exists?(ryan.id) # => true + # ryan.exists? # => true # # ryan = Person.find(1) - # # => Resource holding our newly created Person object + # # Resource holding our newly created Person object # # ryan.first = 'Rizzle' - # ryan.save #=> true + # ryan.save # => true # - # ryan.destroy #=> true + # ryan.destroy # => true # # As you can see, these are very similar to Active Record's lifecycle methods for database records. # You can read more about each of these methods in their respective documentation. @@ -127,7 +127,7 @@ module ActiveResource # # GET http://api.people.com:3000/people/999.xml # ryan = Person.find(999) # 404, raises ActiveResource::ResourceNotFound # - # <tt>404</tt> is just one of the HTTP error response codes that ActiveResource will handle with its own exception. The + # <tt>404</tt> is just one of the HTTP error response codes that Active Resource will handle with its own exception. The # following HTTP response codes will also result in these exceptions: # # * 200..399 - Valid response, no exception @@ -156,8 +156,8 @@ module ActiveResource # then fail (with a <tt>false</tt> return value) and the validation errors can be accessed on the resource in question. # # ryan = Person.find(1) - # ryan.first #=> '' - # ryan.save #=> false + # ryan.first # => '' + # ryan.save # => false # # # When # # PUT http://api.people.com:3000/people/1.xml @@ -167,8 +167,8 @@ module ActiveResource # # <errors type="array"><error>First cannot be empty</error></errors> # # # - # ryan.errors.invalid?(:first) #=> true - # ryan.errors.full_messages #=> ['First cannot be empty'] + # ryan.errors.invalid?(:first) # => true + # ryan.errors.full_messages # => ['First cannot be empty'] # # Learn more about Active Resource's validation features in the ActiveResource::Validations documentation. # @@ -201,7 +201,7 @@ module ActiveResource class << self # Gets the URI of the REST resources to map for this class. The site variable is required - # ActiveResource's mapping to work. + # Active Resource's mapping to work. def site # Not using superclass_delegating_reader because don't want subclasses to modify superclass instance # @@ -226,7 +226,7 @@ module ActiveResource end # Sets the URI of the REST resources to map for this class to the value in the +site+ argument. - # The site variable is required ActiveResource's mapping to work. + # The site variable is required Active Resource's mapping to work. def site=(site) @connection = nil if site.nil? @@ -701,7 +701,7 @@ module ActiveResource attributes[self.class.primary_key] = id end - # Allows ActiveResource objects to be used as parameters in ActionPack URL generation. + # Allows Active Resource objects to be used as parameters in Action Pack URL generation. def to_param id && id.to_s end @@ -820,7 +820,7 @@ module ActiveResource # ==== Options # The +options+ parameter is handed off to the +to_xml+ method on each # attribute, so it has the same options as the +to_xml+ methods in - # ActiveSupport. + # Active Support. # # * <tt>:indent</tt> - Set the indent level for the XML output (default is +2+). # * <tt>:dasherize</tt> - Boolean option to determine whether or not element names should diff --git a/activeresource/lib/active_resource/custom_methods.rb b/activeresource/lib/active_resource/custom_methods.rb index 52a4a4f10b..4c8699288c 100644 --- a/activeresource/lib/active_resource/custom_methods.rb +++ b/activeresource/lib/active_resource/custom_methods.rb @@ -7,12 +7,12 @@ module ActiveResource # :member => { :promote => :put, :deactivate => :delete } # :collection => { :active => :get } # - # This route set creates routes for the following http requests: + # This route set creates routes for the following HTTP requests: # - # POST /people/new/register.xml #=> PeopleController.register - # PUT /people/1/promote.xml #=> PeopleController.promote with :id => 1 - # DELETE /people/1/deactivate.xml #=> PeopleController.deactivate with :id => 1 - # GET /people/active.xml #=> PeopleController.active + # POST /people/new/register.xml # PeopleController.register + # PUT /people/1/promote.xml # PeopleController.promote with :id => 1 + # DELETE /people/1/deactivate.xml # PeopleController.deactivate with :id => 1 + # GET /people/active.xml # PeopleController.active # # Using this module, Active Resource can use these custom REST methods just like the # standard methods. @@ -48,8 +48,8 @@ module ActiveResource # # => [{:id => 1, :name => 'Ryan'}] # # Note: the objects returned from this method are not automatically converted - # into ActiveResource instances - they are ordinary Hashes. If you are expecting - # ActiveResource instances, use the <tt>find</tt> class method with the + # into Active Resource instances - they are ordinary Hashes. If you are expecting + # Active Resource instances, use the <tt>find</tt> class method with the # <tt>:from</tt> option. For example: # # Person.find(:all, :from => :active) diff --git a/activeresource/lib/active_resource/formats/xml_format.rb b/activeresource/lib/active_resource/formats/xml_format.rb index 01c28dcee6..5e97ffa776 100644 --- a/activeresource/lib/active_resource/formats/xml_format.rb +++ b/activeresource/lib/active_resource/formats/xml_format.rb @@ -21,7 +21,7 @@ module ActiveResource private # Manipulate from_xml Hash, because xml_simple is not exactly what we - # want for ActiveResource. + # want for Active Resource. def from_xml_data(data) if data.is_a?(Hash) && data.keys.size == 1 data.values.first diff --git a/activeresource/lib/active_resource/http_mock.rb b/activeresource/lib/active_resource/http_mock.rb index d1c1412575..22f83ae910 100644 --- a/activeresource/lib/active_resource/http_mock.rb +++ b/activeresource/lib/active_resource/http_mock.rb @@ -3,8 +3,52 @@ require 'active_resource/connection' module ActiveResource class InvalidRequestError < StandardError; end #:nodoc: + # One thing that has always been a pain with remote web services is testing. The HttpMock + # class makes it easy to test your Active Resource models by creating a set of mock responses to specific + # requests. + # + # To test your Active Resource model, you simply call the ActiveResource::HttpMock.respond_to + # method with an attached block. The block declares a set of URIs with expected input, and the output + # each request should return. The passed in block has any number of entries in the following generalized + # format: + # + # mock.http_method(path, request_headers = {}, body = nil, status = 200, response_headers = {}) + # + # * <tt>http_method</tt> - The HTTP method to listen for. This can be +get+, +post+, +put+, +delete+ or + # +head+. + # * <tt>path</tt> - A string, starting with a "/", defining the URI that is expected to be + # called. + # * <tt>request_headers</tt> - Headers that are expected along with the request. This argument uses a + # hash format, such as <tt>{ "Content-Type" => "application/xml" }</tt>. This mock will only trigger + # if your tests sends a request with identical headers. + # * <tt>body</tt> - The data to be returned. This should be a string of Active Resource parseable content, + # such as XML. + # * <tt>status</tt> - The HTTP response code, as an integer, to return with the response. + # * <tt>response_headers</tt> - Headers to be returned with the response. Uses the same hash format as + # <tt>request_headers</tt> listed above. + # + # In order for a mock to deliver its content, the incoming request must match by the <tt>http_method</tt>, + # +path+ and <tt>request_headers</tt>. If no match is found an InvalidRequestError exception + # will be raised letting you know you need to create a new mock for that request. + # + # ==== Example + # def setup + # @matz = { :id => 1, :name => "Matz" }.to_xml(:root => "person") + # ActiveResource::HttpMock.respond_to do |mock| + # mock.post "/people.xml", {}, @matz, 201, "Location" => "/people/1.xml" + # mock.get "/people/1.xml", {}, @matz + # mock.put "/people/1.xml", {}, nil, 204 + # mock.delete "/people/1.xml", {}, nil, 200 + # end + # end + # + # def test_get_matz + # person = Person.find(1) + # assert_equal "Matz", person.name + # end + # class HttpMock - class Responder + class Responder #:nodoc: def initialize(responses) @responses = responses end @@ -19,15 +63,41 @@ module ActiveResource end class << self + + # Returns an array of all request objects that have been sent to the mock. You can use this to check + # wether or not your model actually sent an HTTP request. + # + # ==== Example + # def setup + # @matz = { :id => 1, :name => "Matz" }.to_xml(:root => "person") + # ActiveResource::HttpMock.respond_to do |mock| + # mock.get "/people/1.xml", {}, @matz + # end + # end + # + # def test_should_request_remote_service + # person = Person.find(1) # Call the remote service + # + # # This request object has the same HTTP method and path as declared by the mock + # expected_request = ActiveResource::Request.new(:get, "/people/1.xml") + # + # # Assert that the mock received, and responded to, the expected request from the model + # assert ActiveResource::HttpMock.requests.include?(expected_request) + # end def requests @@requests ||= [] end + # Returns a hash of <tt>request => response</tt> pairs for all all responses this mock has delivered, where +request+ + # is an instance of ActiveResource::Request and the response is, naturally, an instance of + # ActiveResource::Response. def responses @@responses ||= {} end - def respond_to(pairs = {}) + # Accepts a block which declares a set of requests and responses for the HttpMock to respond to. See the main + # ActiveResource::HttpMock description for a more detailed explanation. + def respond_to(pairs = {}) #:yields: mock reset! pairs.each do |(path, response)| responses[path] = response @@ -40,6 +110,7 @@ module ActiveResource end end + # Deletes all logged requests and responses. def reset! requests.clear responses.clear @@ -66,7 +137,7 @@ module ActiveResource EOE end - def initialize(site) + def initialize(site) #:nodoc: @site = site end end diff --git a/activeresource/lib/active_resource/validations.rb b/activeresource/lib/active_resource/validations.rb index 57d2ae559d..a7c624f309 100644 --- a/activeresource/lib/active_resource/validations.rb +++ b/activeresource/lib/active_resource/validations.rb @@ -216,8 +216,8 @@ module ActiveResource end end - # 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 + # Module to allow validation of Active Resource 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). # diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb index a023118885..2c606b401b 100644 --- a/activesupport/lib/active_support/core_ext/hash/conversions.rb +++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb @@ -212,7 +212,7 @@ module ActiveSupport #:nodoc: nil # If the type is the only element which makes it then # this still makes the value nil, except if type is - # a xml node(where type['value'] is a Hash) + # a XML node(where type['value'] is a Hash) elsif value['type'] && value.size == 1 && !value['type'].is_a?(::Hash) nil else diff --git a/activesupport/lib/active_support/core_ext/integer/even_odd.rb b/activesupport/lib/active_support/core_ext/integer/even_odd.rb index cfc6b4c6d6..b1d1e28062 100644 --- a/activesupport/lib/active_support/core_ext/integer/even_odd.rb +++ b/activesupport/lib/active_support/core_ext/integer/even_odd.rb @@ -3,10 +3,14 @@ module ActiveSupport #:nodoc: module Integer #:nodoc: # For checking if a fixnum is even or odd. # - # 1.even? # => false - # 1.odd? # => true - # 2.even? # => true - # 2.odd? # => false + # 2.even? # => true + # 2.odd? # => false + # 1.even? # => false + # 1.odd? # => true + # 0.even? # => true + # 0.odd? # => false + # -1.even? # => false + # -1.odd? # => true module EvenOdd def multiple_of?(number) self % number == 0 diff --git a/activesupport/lib/active_support/core_ext/object/misc.rb b/activesupport/lib/active_support/core_ext/object/misc.rb index a3637d7a8a..8384a12327 100644 --- a/activesupport/lib/active_support/core_ext/object/misc.rb +++ b/activesupport/lib/active_support/core_ext/object/misc.rb @@ -48,7 +48,7 @@ class Object yield ActiveSupport::OptionMerger.new(self, options) end - # A duck-type assistant method. For example, ActiveSupport extends Date + # A duck-type assistant method. For example, Active Support extends Date # to define an acts_like_date? method, and extends Time to define # acts_like_time?. As a result, we can do "x.acts_like?(:time)" and # "x.acts_like?(:date)" to do duck-type-safe comparisons, since classes that diff --git a/activesupport/lib/active_support/core_ext/string/unicode.rb b/activesupport/lib/active_support/core_ext/string/unicode.rb index ba16d4d866..5e20534d1d 100644 --- a/activesupport/lib/active_support/core_ext/string/unicode.rb +++ b/activesupport/lib/active_support/core_ext/string/unicode.rb @@ -17,17 +17,17 @@ module ActiveSupport #:nodoc: # string overrides can also be called through the +chars+ proxy. # # name = 'Claus Müller' - # name.reverse #=> "rell??M sualC" - # name.length #=> 13 + # name.reverse # => "rell??M sualC" + # name.length # => 13 # - # name.chars.reverse.to_s #=> "rellüM sualC" - # name.chars.length #=> 12 + # name.chars.reverse.to_s # => "rellüM sualC" + # name.chars.length # => 12 # # # All the methods on the chars proxy which normally return a string will return a Chars object. This allows # method chaining on the result of any of these methods. # - # name.chars.reverse.length #=> 12 + # name.chars.reverse.length # => 12 # # The Char object tries to be as interchangeable with String objects as possible: sorting and comparing between # String and Char work like expected. The bang! methods change the internal string representation in the Chars diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb index edca5b8a98..9054008309 100644 --- a/activesupport/lib/active_support/core_ext/time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/time/conversions.rb @@ -59,7 +59,7 @@ module ActiveSupport #:nodoc: # Converts a Time object to a Date, dropping hour, minute, and second precision. # # my_time = Time.now # => Mon Nov 12 22:59:51 -0500 2007 - # my_time.to_date #=> Mon, 12 Nov 2007 + # my_time.to_date # => Mon, 12 Nov 2007 # # your_time = Time.parse("1/13/2009 1:13:03 P.M.") # => Tue Jan 13 13:13:03 -0500 2009 # your_time.to_date # => Tue, 13 Jan 2009 diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb index cf28d0fa95..079ecdd48e 100644 --- a/activesupport/lib/active_support/core_ext/time/zones.rb +++ b/activesupport/lib/active_support/core_ext/time/zones.rb @@ -10,21 +10,21 @@ module ActiveSupport #:nodoc: attr_accessor :zone_default # Returns the TimeZone for the current request, if this has been set (via Time.zone=). - # If Time.zone has not been set for the current request, returns the TimeZone specified in config.time_zone + # If <tt>Time.zone</tt> has not been set for the current request, returns the TimeZone specified in <tt>config.time_zone</tt>. def zone Thread.current[:time_zone] || zone_default end - # Sets Time.zone to a TimeZone object for the current request/thread. + # Sets <tt>Time.zone</tt> to a TimeZone object for the current request/thread. # # This method accepts any of the following: # - # * a Rails TimeZone object - # * an identifier for a Rails TimeZone object (e.g., "Eastern Time (US & Canada)", -5.hours) - # * a TZInfo::Timezone object - # * an identifier for a TZInfo::Timezone object (e.g., "America/New_York") + # * A Rails TimeZone object. + # * An identifier for a Rails TimeZone object (e.g., "Eastern Time (US & Canada)", <tt>-5.hours</tt>). + # * A TZInfo::Timezone object. + # * An identifier for a TZInfo::Timezone object (e.g., "America/New_York"). # - # Here's an example of how you might set Time.zone on a per request basis -- current_user.time_zone + # Here's an example of how you might set <tt>Time.zone</tt> on a per request basis -- <tt>current_user.time_zone</tt> # just needs to return a string identifying the user's preferred TimeZone: # # class ApplicationController < ActionController::Base @@ -38,7 +38,7 @@ module ActiveSupport #:nodoc: Thread.current[:time_zone] = get_zone(time_zone) end - # Allows override of Time.zone locally inside supplied block; resets Time.zone to existing value when done + # Allows override of <tt>Time.zone</tt> locally inside supplied block; resets <tt>Time.zone</tt> to existing value when done. def use_zone(time_zone) old_zone, ::Time.zone = ::Time.zone, get_zone(time_zone) yield @@ -46,7 +46,7 @@ module ActiveSupport #:nodoc: ::Time.zone = old_zone end - # Returns Time.zone.now when config.time_zone is set, otherwise just returns Time.now. + # Returns <tt>Time.zone.now</tt> when <tt>config.time_zone</tt> is set, otherwise just returns <tt>Time.now</tt>. def current ::Time.zone_default ? ::Time.zone.now : ::Time.now end @@ -65,16 +65,16 @@ module ActiveSupport #:nodoc: end end - # Returns the simultaneous time in Time.zone. + # Returns the simultaneous time in <tt>Time.zone</tt>. # # Time.zone = 'Hawaii' # => 'Hawaii' # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 # - # This method is similar to Time#localtime, except that it uses Time.zone as the local zone + # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone # instead of the operating system's time zone. # # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument, - # and the conversion will be based on that zone instead of Time.zone. + # and the conversion will be based on that zone instead of <tt>Time.zone</tt>. # # Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 def in_time_zone(zone = ::Time.zone) diff --git a/activesupport/lib/active_support/deprecation.rb b/activesupport/lib/active_support/deprecation.rb index 6aa379b550..758aef5445 100644 --- a/activesupport/lib/active_support/deprecation.rb +++ b/activesupport/lib/active_support/deprecation.rb @@ -144,8 +144,8 @@ module ActiveSupport end end - # Stand-in for @request, @attributes, @params, etc which emits deprecation - # warnings on any method call (except #inspect). + # Stand-in for <tt>@request</tt>, <tt>@attributes</tt>, <tt>@params</tt>, etc. + # which emits deprecation warnings on any method call (except +inspect+). class DeprecatedInstanceVariableProxy #:nodoc: silence_warnings do instance_methods.each { |m| undef_method m unless m =~ /^__/ } diff --git a/activesupport/lib/active_support/inflector.rb b/activesupport/lib/active_support/inflector.rb index 0fd44324bb..a4fd619317 100644 --- a/activesupport/lib/active_support/inflector.rb +++ b/activesupport/lib/active_support/inflector.rb @@ -109,13 +109,13 @@ module Inflector # Returns the plural form of the word in the string. # - # Examples - # "post".pluralize #=> "posts" - # "octopus".pluralize #=> "octopi" - # "sheep".pluralize #=> "sheep" - # "words".pluralize #=> "words" - # "the blue mailman".pluralize #=> "the blue mailmen" - # "CamelOctopus".pluralize #=> "CamelOctopi" + # Examples: + # "post".pluralize # => "posts" + # "octopus".pluralize # => "octopi" + # "sheep".pluralize # => "sheep" + # "words".pluralize # => "words" + # "the blue mailman".pluralize # => "the blue mailmen" + # "CamelOctopus".pluralize # => "CamelOctopi" def pluralize(word) result = word.to_s.dup @@ -127,15 +127,15 @@ module Inflector end end - # The reverse of pluralize, returns the singular form of a word in a string. + # The reverse of +pluralize+, returns the singular form of a word in a string. # - # Examples - # "posts".singularize #=> "post" - # "octopi".singularize #=> "octopus" - # "sheep".singluarize #=> "sheep" - # "word".singluarize #=> "word" - # "the blue mailmen".singularize #=> "the blue mailman" - # "CamelOctopi".singularize #=> "CamelOctopus" + # Examples: + # "posts".singularize # => "post" + # "octopi".singularize # => "octopus" + # "sheep".singluarize # => "sheep" + # "word".singluarize # => "word" + # "the blue mailmen".singularize # => "the blue mailman" + # "CamelOctopi".singularize # => "CamelOctopus" def singularize(word) result = word.to_s.dup @@ -147,16 +147,16 @@ module Inflector end end - # By default, camelize converts strings to UpperCamelCase. If the argument to camelize - # is set to ":lower" then camelize produces lowerCamelCase. + # By default, +camelize+ converts strings to UpperCamelCase. If the argument to +camelize+ + # is set to <tt>:lower</tt> then +camelize+ produces lowerCamelCase. # - # camelize will also convert '/' to '::' which is useful for converting paths to namespaces + # +camelize+ will also convert '/' to '::' which is useful for converting paths to namespaces. # - # Examples - # "active_record".camelize #=> "ActiveRecord" - # "active_record".camelize(:lower) #=> "activeRecord" - # "active_record/errors".camelize #=> "ActiveRecord::Errors" - # "active_record/errors".camelize(:lower) #=> "activeRecord::Errors" + # Examples: + # "active_record".camelize # => "ActiveRecord" + # "active_record".camelize(:lower) # => "activeRecord" + # "active_record/errors".camelize # => "ActiveRecord::Errors" + # "active_record/errors".camelize(:lower) # => "activeRecord::Errors" def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true) if first_letter_in_uppercase lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase } @@ -166,14 +166,14 @@ module Inflector end # Capitalizes all the words and replaces some characters in the string to create - # a nicer looking title. Titleize is meant for creating pretty output. It is not + # a nicer looking title. +titleize+ is meant for creating pretty output. It is not # used in the Rails internals. # - # titleize is also aliased as as titlecase + # +titleize+ is also aliased as as +titlecase+. # - # Examples - # "man from the boondocks".titleize #=> "Man From The Boondocks" - # "x-men: the last stand".titleize #=> "X Men: The Last Stand" + # Examples: + # "man from the boondocks".titleize # => "Man From The Boondocks" + # "x-men: the last stand".titleize # => "X Men: The Last Stand" def titleize(word) humanize(underscore(word)).gsub(/\b('?[a-z])/) { $1.capitalize } end @@ -182,9 +182,9 @@ module Inflector # # Changes '::' to '/' to convert namespaces to paths. # - # Examples - # "ActiveRecord".underscore #=> "active_record" - # "ActiveRecord::Errors".underscore #=> active_record/errors + # Examples: + # "ActiveRecord".underscore # => "active_record" + # "ActiveRecord::Errors".underscore # => active_record/errors def underscore(camel_cased_word) camel_cased_word.to_s.gsub(/::/, '/'). gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2'). @@ -195,52 +195,52 @@ module Inflector # Replaces underscores with dashes in the string. # - # Example - # "puni_puni" #=> "puni-puni" + # Example: + # "puni_puni" # => "puni-puni" def dasherize(underscored_word) underscored_word.gsub(/_/, '-') end - # Capitalizes the first word and turns underscores into spaces and strips _id. - # Like titleize, this is meant for creating pretty output. + # Capitalizes the first word and turns underscores into spaces and strips a + # trailing "_id", if any. Like +titleize+, this is meant for creating pretty output. # - # Examples - # "employee_salary" #=> "Employee salary" - # "author_id" #=> "Author" + # Examples: + # "employee_salary" # => "Employee salary" + # "author_id" # => "Author" def humanize(lower_case_and_underscored_word) lower_case_and_underscored_word.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize end - # Removes the module part from the expression in the string + # Removes the module part from the expression in the string. # - # Examples - # "ActiveRecord::CoreExtensions::String::Inflections".demodulize #=> "Inflections" - # "Inflections".demodulize #=> "Inflections" + # Examples: + # "ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections" + # "Inflections".demodulize # => "Inflections" def demodulize(class_name_in_module) class_name_in_module.to_s.gsub(/^.*::/, '') end # Create the name of a table like Rails does for models to table names. This method - # uses the pluralize method on the last word in the string. + # uses the +pluralize+ method on the last word in the string. # # Examples - # "RawScaledScorer".tableize #=> "raw_scaled_scorers" - # "egg_and_ham".tableize #=> "egg_and_hams" - # "fancyCategory".tableize #=> "fancy_categories" + # "RawScaledScorer".tableize # => "raw_scaled_scorers" + # "egg_and_ham".tableize # => "egg_and_hams" + # "fancyCategory".tableize # => "fancy_categories" def tableize(class_name) pluralize(underscore(class_name)) end # Create a class name from a plural table name like Rails does for table names to models. # Note that this returns a string and not a Class. (To convert to an actual class - # follow classify with constantize.) + # follow +classify+ with +constantize+.) # - # Examples - # "egg_and_hams".classify #=> "EggAndHam" - # "posts".classify #=> "Post" + # Examples: + # "egg_and_hams".classify # => "EggAndHam" + # "posts".classify # => "Post" # - # Singular names are not handled correctly - # "business".classify #=> "Busines" + # Singular names are not handled correctly: + # "business".classify # => "Busines" def classify(table_name) # strip out any leading schema name camelize(singularize(table_name.to_s.sub(/.*\./, ''))) @@ -250,10 +250,10 @@ module Inflector # +separate_class_name_and_id_with_underscore+ sets whether # the method should put '_' between the name and 'id'. # - # Examples - # "Message".foreign_key #=> "message_id" - # "Message".foreign_key(false) #=> "messageid" - # "Admin::Post".foreign_key #=> "post_id" + # Examples: + # "Message".foreign_key # => "message_id" + # "Message".foreign_key(false) # => "messageid" + # "Admin::Post".foreign_key # => "post_id" def foreign_key(class_name, separate_class_name_and_id_with_underscore = true) underscore(demodulize(class_name)) + (separate_class_name_and_id_with_underscore ? "_id" : "id") end @@ -283,10 +283,10 @@ module Inflector Object.module_eval("::#{$1}", __FILE__, __LINE__) end - # Ordinalize turns a number into an ordinal string used to denote the - # position in an ordered sequence such as 1st, 2nd, 3rd, 4th. + # Turns a number into an ordinal string used to denote the position in an + # ordered sequence such as 1st, 2nd, 3rd, 4th. # - # Examples + # Examples: # ordinalize(1) # => "1st" # ordinalize(2) # => "2nd" # ordinalize(1002) # => "1002nd" diff --git a/activesupport/lib/active_support/json.rb b/activesupport/lib/active_support/json.rb index bbda2c9fa3..54a7becd0f 100644 --- a/activesupport/lib/active_support/json.rb +++ b/activesupport/lib/active_support/json.rb @@ -1,5 +1,5 @@ module ActiveSupport - # If true, use ISO 8601 format for dates and times. Otherwise, fall back to the ActiveSupport legacy format. + # If true, use ISO 8601 format for dates and times. Otherwise, fall back to the Active Support legacy format. mattr_accessor :use_standard_json_time_format class << self diff --git a/activesupport/lib/active_support/json/decoding.rb b/activesupport/lib/active_support/json/decoding.rb index c58001f49f..fdb219dbf7 100644 --- a/activesupport/lib/active_support/json/decoding.rb +++ b/activesupport/lib/active_support/json/decoding.rb @@ -31,7 +31,7 @@ module ActiveSupport if json[pos..scanner.pos-2] =~ DATE_REGEX # found a date, track the exact positions of the quotes so we can remove them later. # oh, and increment them for each current mark, each one is an extra padded space that bumps - # the position in the final yaml output + # the position in the final YAML output total_marks = marks.size times << pos+total_marks << scanner.pos+total_marks end diff --git a/activesupport/lib/active_support/multibyte/chars.rb b/activesupport/lib/active_support/multibyte/chars.rb index 65114415eb..ee716de39e 100644 --- a/activesupport/lib/active_support/multibyte/chars.rb +++ b/activesupport/lib/active_support/multibyte/chars.rb @@ -10,7 +10,7 @@ module ActiveSupport::Multibyte #:nodoc: # String methods are proxied through the Chars object, and can be accessed through the +chars+ method. Methods # which would normally return a String object now return a Chars object so methods can be chained. # - # "The Perfect String ".chars.downcase.strip.normalize #=> "the perfect string" + # "The Perfect String ".chars.downcase.strip.normalize # => "the perfect string" # # Chars objects are perfectly interchangeable with String objects as long as no explicit class checks are made. # If certain methods do explicitly check the class, call +to_s+ before you pass chars objects to them. diff --git a/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb b/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb index 0166b69ac3..aa9c16f575 100644 --- a/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb +++ b/activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb @@ -147,13 +147,11 @@ module ActiveSupport::Multibyte::Handlers #:nodoc: # # s = "Müller" # s.chars[2] = "e" # Replace character with offset 2 - # s - # #=> "Müeler" + # s # => "Müeler" # # s = "Müller" # s.chars[1, 2] = "ö" # Replace 2 characters at character offset 1 - # s - # #=> "Möler" + # s # => "Möler" def []=(str, *args) replace_by = args.pop # Indexed replace with regular expressions already works @@ -183,10 +181,10 @@ module ActiveSupport::Multibyte::Handlers #:nodoc: # Example: # # "¾ cup".chars.rjust(8).to_s - # #=> " ¾ cup" + # # => " ¾ cup" # # "¾ cup".chars.rjust(8, " ").to_s # Use non-breaking whitespace - # #=> " ¾ cup" + # # => " ¾ cup" def rjust(str, integer, padstr=' ') justify(str, integer, :right, padstr) end @@ -196,10 +194,10 @@ module ActiveSupport::Multibyte::Handlers #:nodoc: # Example: # # "¾ cup".chars.rjust(8).to_s - # #=> "¾ cup " + # # => "¾ cup " # # "¾ cup".chars.rjust(8, " ").to_s # Use non-breaking whitespace - # #=> "¾ cup " + # # => "¾ cup " def ljust(str, integer, padstr=' ') justify(str, integer, :left, padstr) end @@ -209,10 +207,10 @@ module ActiveSupport::Multibyte::Handlers #:nodoc: # Example: # # "¾ cup".chars.center(8).to_s - # #=> " ¾ cup " + # # => " ¾ cup " # # "¾ cup".chars.center(8, " ").to_s # Use non-breaking whitespace - # #=> " ¾ cup " + # # => " ¾ cup " def center(str, integer, padstr=' ') justify(str, integer, :center, padstr) end diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb index 64c935717d..ece95eeae9 100644 --- a/activesupport/lib/active_support/time_with_zone.rb +++ b/activesupport/lib/active_support/time_with_zone.rb @@ -1,10 +1,10 @@ require 'tzinfo' module ActiveSupport # A Time-like class that can represent a time in any time zone. Necessary because standard Ruby Time instances are - # limited to UTC and the system's ENV['TZ'] zone. + # limited to UTC and the system's <tt>ENV['TZ']</tt> zone. # - # You shouldn't ever need to create a TimeWithZone instance directly via .new -- instead, Rails provides the methods - # #local, #parse, #at and #now on TimeZone instances, and #in_time_zone on Time and DateTime instances, for a more + # You shouldn't ever need to create a TimeWithZone instance directly via <tt>new</tt> -- instead, Rails provides the methods + # +local+, +parse+, +at+ and +now+ on TimeZone instances, and +in_time_zone+ on Time and DateTime instances, for a more # user-friendly syntax. Examples: # # Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)' @@ -38,12 +38,12 @@ module ActiveSupport @period = @utc ? period : get_period_and_ensure_valid_local_time end - # Returns a Time or DateTime instance that represents the time in time_zone + # Returns a Time or DateTime instance that represents the time in +time_zone+. def time @time ||= period.to_local(@utc) end - # Returns a Time or DateTime instance that represents the time in UTC + # Returns a Time or DateTime instance that represents the time in UTC. def utc @utc ||= period.to_utc(@time) end @@ -52,18 +52,18 @@ module ActiveSupport alias_method :getutc, :utc alias_method :gmtime, :utc - # Returns the underlying TZInfo::TimezonePeriod + # Returns the underlying TZInfo::TimezonePeriod. def period @period ||= time_zone.period_for_utc(@utc) end - # Returns the simultaneous time in Time.zone, or the specified zone + # Returns the simultaneous time in <tt>Time.zone</tt>, or the specified zone. def in_time_zone(new_zone = ::Time.zone) return self if time_zone == new_zone utc.in_time_zone(new_zone) end - # Returns a Time.local() instance of the simultaneous time in your system's ENV['TZ'] zone + # Returns a <tt>Time.local()</tt> instance of the simultaneous time in your system's <tt>ENV['TZ']</tt> zone def localtime utc.getlocal end @@ -89,7 +89,7 @@ module ActiveSupport utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon) end - # Time uses #zone to display the time zone abbreviation, so we're duck-typing it + # Time uses +zone+ to display the time zone abbreviation, so we're duck-typing it. def zone period.zone_identifier.to_s end @@ -146,7 +146,7 @@ module ActiveSupport time.strftime(format) end - # Use the time in UTC for comparisons + # Use the time in UTC for comparisons. def <=>(other) utc <=> other end @@ -159,8 +159,8 @@ module ActiveSupport utc == other end - # If wrapped #time is a DateTime, use DateTime#since instead of #+ - # Otherwise, just pass on to #method_missing + # If wrapped +time+ is a DateTime, use DateTime#since instead of <tt>+</tt>. + # Otherwise, just pass on to +method_missing+. def +(other) result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other) result.in_time_zone(time_zone) @@ -225,18 +225,18 @@ module ActiveSupport utc.to_datetime.new_offset(Rational(utc_offset, 86_400)) end - # so that self acts_like?(:time) + # So that +self+ <tt>acts_like?(:time)</tt>. def acts_like_time? true end - # Say we're a Time to thwart type checking + # Say we're a Time to thwart type checking. def is_a?(klass) klass == ::Time || super end alias_method :kind_of?, :is_a? - # Neuter freeze because freezing can cause problems with lazy loading of attributes + # Neuter freeze because freezing can cause problems with lazy loading of attributes. def freeze self end @@ -249,14 +249,14 @@ module ActiveSupport initialize(variables[0], ::Time.send!(:get_zone, variables[1]), variables[2]) end - # Ensure proxy class responds to all methods that underlying time instance responds to + # Ensure proxy class responds to all methods that underlying time instance responds to. def respond_to?(sym) # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime return false if sym.to_s == 'acts_like_date?' super || time.respond_to?(sym) end - # Send the missing method to time instance, and wrap result in a new TimeWithZone with the existing time_zone + # Send the missing method to +time+ instance, and wrap result in a new TimeWithZone with the existing +time_zone+. def method_missing(sym, *args, &block) result = time.__send__(sym, *args, &block) result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb index 5340b5ed28..4d7239d8cf 100644 --- a/activesupport/lib/active_support/values/time_zone.rb +++ b/activesupport/lib/active_support/values/time_zone.rb @@ -1,11 +1,11 @@ # The TimeZone class serves as a wrapper around TZInfo::Timezone instances. It allows us to do the following: # -# * limit the set of zones provided by TZInfo to a meaningful subset of 142 zones -# * retrieve and display zones with a friendlier name (e.g., "Eastern Time (US & Canada)" instead of "America/New_York") -# * lazily load TZInfo::Timezone instances only when they're needed -# * create ActiveSupport::TimeWithZone instances via TimeZone #local, #parse, #at and #now methods +# * Limit the set of zones provided by TZInfo to a meaningful subset of 142 zones. +# * Retrieve and display zones with a friendlier name (e.g., "Eastern Time (US & Canada)" instead of "America/New_York"). +# * Lazily load TZInfo::Timezone instances only when they're needed. +# * Create ActiveSupport::TimeWithZone instances via TimeZone's +local+, +parse+, +at+ and +now+ methods. # -# If you set config.time_zone in the Rails Initializer, you can access this TimeZone object via Time.zone: +# If you set <tt>config.time_zone</tt> in the Rails Initializer, you can access this TimeZone object via <tt>Time.zone</tt>: # # # environment.rb: # Rails::Initializer.run do |config| @@ -16,7 +16,7 @@ # Time.zone.name # => "Eastern Time (US & Canada)" # Time.zone.now # => Sun, 18 May 2008 14:30:44 EDT -04:00 # -# The version of TZInfo bundled with ActiveSupport only includes the definitions necessary to support the zones +# The version of TZInfo bundled with Active Support only includes the definitions necessary to support the zones # defined by the TimeZone class. If you need to use zones that aren't defined by TimeZone, you'll need to install the TZInfo gem # (if a recent version of the gem is installed locally, this will be used instead of the bundled version.) class TimeZone @@ -356,7 +356,7 @@ class TimeZone # Return a TimeZone instance with the given name, or +nil+ if no # such TimeZone instance exists. (This exists to support the use of - # this class with the #composed_of macro.) + # this class with the +composed_of+ macro.) def new(name) self[name] end diff --git a/railties/configs/databases/frontbase.yml b/railties/configs/databases/frontbase.yml index 2eed3133a1..c0c3588be1 100644 --- a/railties/configs/databases/frontbase.yml +++ b/railties/configs/databases/frontbase.yml @@ -10,8 +10,8 @@ development: username: <%= app_name %> password: '' -# Warning: The database defined as 'test' will be erased and -# re-generated from your development database when you run 'rake'. +# Warning: The database defined as "test" will be erased and +# re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: adapter: frontbase diff --git a/railties/configs/databases/mysql.yml b/railties/configs/databases/mysql.yml index c5c894c5e1..7fcadcdf2c 100644 --- a/railties/configs/databases/mysql.yml +++ b/railties/configs/databases/mysql.yml @@ -26,8 +26,8 @@ development: host: localhost <% end -%> -# Warning: The database defined as 'test' will be erased and -# re-generated from your development database when you run 'rake'. +# Warning: The database defined as "test" will be erased and +# re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: adapter: mysql diff --git a/railties/configs/databases/oracle.yml b/railties/configs/databases/oracle.yml index c86cbdbaba..a1883f6256 100644 --- a/railties/configs/databases/oracle.yml +++ b/railties/configs/databases/oracle.yml @@ -4,7 +4,7 @@ # http://rubyforge.org/projects/ruby-oci8/ # # Specify your database using any valid connection syntax, such as a -# tnsnames.ora service name, or a sql connect url string of the form: +# tnsnames.ora service name, or a SQL connect url string of the form: # # //host:[port][/service name] # @@ -23,8 +23,8 @@ development: username: <%= app_name %> password: -# Warning: The database defined as 'test' will be erased and -# re-generated from your development database when you run 'rake'. +# Warning: The database defined as "test" will be erased and +# re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: adapter: oracle diff --git a/railties/configs/databases/postgresql.yml b/railties/configs/databases/postgresql.yml index c1b911a9a4..36f6e5ae49 100644 --- a/railties/configs/databases/postgresql.yml +++ b/railties/configs/databases/postgresql.yml @@ -30,8 +30,8 @@ development: # The server defaults to notice. #min_messages: warning -# Warning: The database defined as 'test' will be erased and -# re-generated from your development database when you run 'rake'. +# Warning: The database defined as "test" will be erased and +# re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: adapter: postgresql diff --git a/railties/configs/databases/sqlite2.yml b/railties/configs/databases/sqlite2.yml index 26d3957d79..fc48bd6753 100644 --- a/railties/configs/databases/sqlite2.yml +++ b/railties/configs/databases/sqlite2.yml @@ -4,8 +4,8 @@ development: adapter: sqlite database: db/development.sqlite2 -# Warning: The database defined as 'test' will be erased and -# re-generated from your development database when you run 'rake'. +# Warning: The database defined as "test" will be erased and +# re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: adapter: sqlite diff --git a/railties/configs/databases/sqlite3.yml b/railties/configs/databases/sqlite3.yml index b444b03cd4..fff44a4124 100644 --- a/railties/configs/databases/sqlite3.yml +++ b/railties/configs/databases/sqlite3.yml @@ -5,8 +5,8 @@ development: database: db/development.sqlite3 timeout: 5000 -# Warning: The database defined as 'test' will be erased and -# re-generated from your development database when you run 'rake'. +# Warning: The database defined as "test" will be erased and +# re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: adapter: sqlite3 diff --git a/railties/configs/initializers/new_rails_defaults.rb b/railties/configs/initializers/new_rails_defaults.rb index b959c6d549..5e60c0ade4 100644 --- a/railties/configs/initializers/new_rails_defaults.rb +++ b/railties/configs/initializers/new_rails_defaults.rb @@ -1,15 +1,15 @@ # These settings change the behavior of Rails 2 apps and will be defaults # for Rails 3. You can remove this initializer when Rails 3 is released. -# Include ActiveRecord class name as root for JSON serialized output. +# Include Active Record class name as root for JSON serialized output. ActiveRecord::Base.include_root_in_json = true -# Store the full class name (including module namespace) in STI type column +# Store the full class name (including module namespace) in STI type column. ActiveRecord::Base.store_full_sti_class = true -# Use ISO 8601 format for JSON serialized times and dates +# Use ISO 8601 format for JSON serialized times and dates. ActiveSupport.use_standard_json_time_format = true -# Don't escape HTML entities in JSON, leave that for the #json_escape helper +# Don't escape HTML entities in JSON, leave that for the #json_escape helper. # if you're including raw json in an HTML page. ActiveSupport.escape_html_entities_in_json = false
\ No newline at end of file diff --git a/railties/environments/environment.rb b/railties/environments/environment.rb index d03447e1d3..468fa45ef6 100644 --- a/railties/environments/environment.rb +++ b/railties/environments/environment.rb @@ -21,7 +21,7 @@ Rails::Initializer.run do |config| # config.frameworks -= [ :active_record, :active_resource, :action_mailer ] # Specify gems that this application depends on. - # They can then be installed with rake gem:install on new installations. + # They can then be installed with "rake gems:install" on new installations. # config.gem "bj" # config.gem "hpricot", :version => '0.6', :source => "http://code.whytheluckystiff.net" # config.gem "aws-s3", :lib => "aws/s3" @@ -38,9 +38,9 @@ Rails::Initializer.run do |config| # (by default production uses :info, the others :debug) # config.log_level = :debug - # Make Time.zone default to the specified zone, and make ActiveRecord store time values + # Make Time.zone default to the specified zone, and make Active Record store time values # in the database in UTC, and return them converted to the specified local zone. - # Run `rake -D time` for a list of tasks for finding time zone names. Uncomment to use default local time. + # Run "rake -D time" for a list of tasks for finding time zone names. Uncomment to use default local time. config.time_zone = 'UTC' # Your secret key for verifying cookie session data integrity. @@ -54,7 +54,7 @@ Rails::Initializer.run do |config| # Use the database for sessions instead of the cookie-based default, # which shouldn't be used to store highly confidential information - # (create the session table with 'rake db:sessions:create') + # (create the session table with "rake db:sessions:create") # config.action_controller.session_store = :active_record_store # Use SQL instead of Active Record's schema dumper when creating the test database. diff --git a/railties/environments/test.rb b/railties/environments/test.rb index 58850a7974..1e709e1d19 100644 --- a/railties/environments/test.rb +++ b/railties/environments/test.rb @@ -16,7 +16,7 @@ config.action_controller.perform_caching = false # Disable request forgery protection in test environment config.action_controller.allow_forgery_protection = false -# Tell ActionMailer not to deliver emails to the real world. +# Tell Action Mailer not to deliver emails to the real world. # The :test delivery method accumulates sent emails in the # ActionMailer::Base.deliveries array. config.action_mailer.delivery_method = :test diff --git a/railties/lib/initializer.rb b/railties/lib/initializer.rb index 2e56485989..8f963cb4a5 100644 --- a/railties/lib/initializer.rb +++ b/railties/lib/initializer.rb @@ -164,12 +164,12 @@ module Rails end # If Rails is vendored and RubyGems is available, install stub GemSpecs - # for Rails, ActiveSupport, ActiveRecord, ActionPack, ActionMailer, and - # ActiveResource. This allows Gem plugins to depend on Rails even when + # for Rails, Active Support, Active Record, Action Pack, Action Mailer, and + # Active Resource. This allows Gem plugins to depend on Rails even when # the Gem version of Rails shouldn't be loaded. def install_gem_spec_stubs unless Rails.respond_to?(:vendor_rails?) - abort "Your config/boot.rb is outdated: Run 'rake rails:update'." + abort %{Your config/boot.rb is outdated: Run "rake rails:update".} end if Rails.vendor_rails? @@ -214,8 +214,8 @@ module Rails end # Requires all frameworks specified by the Configuration#frameworks - # list. By default, all frameworks (ActiveRecord, ActiveSupport, - # ActionPack, ActionMailer, and ActiveResource) are loaded. + # list. By default, all frameworks (Active Record, Active Support, + # Action Pack, Action Mailer, and Active Resource) are loaded. def require_frameworks configuration.frameworks.each { |framework| require(framework.to_s) } rescue LoadError => e @@ -289,7 +289,7 @@ module Rails def load_observers if configuration.frameworks.include?(:active_record) if @configuration.gems.any? { |g| !g.loaded? } - puts "Unable to instantiate observers, some gems that this application depends on are missing. Run 'rake gems:install'" + puts %{Unable to instantiate observers, some gems that this application depends on are missing. Run "rake gems:install"} else ActiveRecord::Base.instantiate_observers end @@ -330,7 +330,7 @@ module Rails end end - # If the +RAILS_DEFAULT_LOGGER+ constant is already set, this initialization + # If the RAILS_DEFAULT_LOGGER constant is already set, this initialization # routine does nothing. If the constant is not set, and Configuration#logger # is not +nil+, this also does nothing. Otherwise, a new logger instance # is created at Configuration#log_path, with a default log level of @@ -363,10 +363,10 @@ module Rails silence_warnings { Object.const_set "RAILS_DEFAULT_LOGGER", logger } end - # Sets the logger for ActiveRecord, ActionController, and ActionMailer + # Sets the logger for Active Record, Action Controller, and Action Mailer # (but only for those frameworks that are to be loaded). If the framework's # logger is already set, it is not changed, otherwise it is set to use - # +RAILS_DEFAULT_LOGGER+. + # RAILS_DEFAULT_LOGGER. def initialize_framework_logging for framework in ([ :active_record, :action_controller, :action_mailer ] & configuration.frameworks) framework.to_s.camelize.constantize.const_get("Base").logger ||= RAILS_DEFAULT_LOGGER @@ -384,7 +384,7 @@ module Rails ActionController::Base.view_paths = [configuration.view_path] if configuration.frameworks.include?(:action_controller) && ActionController::Base.view_paths.empty? end - # If ActionController is not one of the loaded frameworks (Configuration#frameworks) + # If Action Controller is not one of the loaded frameworks (Configuration#frameworks) # this does nothing. Otherwise, it loads the routing definitions and sets up # loading module used to lazily load controllers (Configuration#controller_paths). def initialize_routing @@ -413,13 +413,13 @@ module Rails end end - # Sets the default value for Time.zone, and turns on ActiveRecord time_zone_aware_attributes. + # Sets the default value for Time.zone, and turns on ActiveRecord::Base#time_zone_aware_attributes. # If assigned value cannot be matched to a TimeZone, an exception will be raised. def initialize_time_zone if configuration.time_zone zone_default = Time.send!(:get_zone, configuration.time_zone) unless zone_default - raise "Value assigned to config.time_zone not recognized. Run `rake -D time` for a list of tasks for finding appropriate time zone names." + raise %{Value assigned to config.time_zone not recognized. Run "rake -D time" for a list of tasks for finding appropriate time zone names.} end Time.zone_default = zone_default if configuration.frameworks.include?(:active_record) @@ -479,22 +479,22 @@ module Rails # The application's base directory. attr_reader :root_path - # A stub for setting options on ActionController::Base + # A stub for setting options on ActionController::Base. attr_accessor :action_controller - # A stub for setting options on ActionMailer::Base + # A stub for setting options on ActionMailer::Base. attr_accessor :action_mailer - # A stub for setting options on ActionView::Base + # A stub for setting options on ActionView::Base. attr_accessor :action_view - # A stub for setting options on ActiveRecord::Base + # A stub for setting options on ActiveRecord::Base. attr_accessor :active_record - # A stub for setting options on ActiveRecord::Base + # A stub for setting options on ActiveRecord::Base. attr_accessor :active_resource - # A stub for setting options on ActiveSupport + # A stub for setting options on ActiveSupport. attr_accessor :active_support # Whether or not classes should be cached (set to false if you want @@ -622,9 +622,9 @@ module Rails end alias_method :breakpoint_server=, :breakpoint_server - # Sets the default time_zone. Setting this will enable time_zone - # awareness for ActiveRecord models and set the ActiveRecord default - # timezone to :utc. + # Sets the default +time_zone+. Setting this will enable +time_zone+ + # awareness for Active Record models and set the Active Record default + # timezone to <tt>:utc</tt>. attr_accessor :time_zone # Create a new Configuration instance, initialized with the default @@ -689,7 +689,7 @@ module Rails end # Return the currently selected environment. By default, it returns the - # value of the +RAILS_ENV+ constant. + # value of the RAILS_ENV constant. def environment ::RAILS_ENV end @@ -847,7 +847,7 @@ end # Needs to be duplicated from Active Support since its needed before Active # Support is available. Here both Options and Hash are namespaced to prevent -# conflicts with other implementations AND with the classes residing in ActiveSupport. +# conflicts with other implementations AND with the classes residing in Active Support. class Rails::OrderedOptions < Array #:nodoc: def []=(key, value) key = key.to_sym diff --git a/railties/lib/rails_generator/base.rb b/railties/lib/rails_generator/base.rb index 1ebcff9062..b5cfe79867 100644 --- a/railties/lib/rails_generator/base.rb +++ b/railties/lib/rails_generator/base.rb @@ -36,7 +36,7 @@ module Rails # view.html.erb # # The directory name (+controller+) matches the name of the generator file - # (controller_generator.rb) and class (+ControllerGenerator+). The files + # (controller_generator.rb) and class (ControllerGenerator). The files # that will be copied or used as templates are stored in the +templates+ # directory. # diff --git a/railties/lib/tasks/databases.rake b/railties/lib/tasks/databases.rake index f40f8463f7..8077d0a401 100644 --- a/railties/lib/tasks/databases.rake +++ b/railties/lib/tasks/databases.rake @@ -173,7 +173,7 @@ namespace :db do pending_migrations.each do |pending_migration| puts ' %4d %s' % [pending_migration.version, pending_migration.name] end - abort "Run `rake db:migrate` to update your database then try again." + abort %{Run "rake db:migrate" to update your database then try again.} end end end diff --git a/railties/test/fixtures/about_yml_plugins/bad_about_yml/about.yml b/railties/test/fixtures/about_yml_plugins/bad_about_yml/about.yml index 79d5721a53..fe80872a16 100644 --- a/railties/test/fixtures/about_yml_plugins/bad_about_yml/about.yml +++ b/railties/test/fixtures/about_yml_plugins/bad_about_yml/about.yml @@ -1 +1 @@ -# an empty yaml file - any content in here seems to get parsed as a string
\ No newline at end of file +# an empty YAML file - any content in here seems to get parsed as a string
\ No newline at end of file diff --git a/railties/test/generators/generator_test_helper.rb b/railties/test/generators/generator_test_helper.rb index c99df6e2d3..05dca3400e 100644 --- a/railties/test/generators/generator_test_helper.rb +++ b/railties/test/generators/generator_test_helper.rb @@ -86,19 +86,19 @@ class GeneratorTestCase < Test::Unit::TestCase # don't complain, test/unit end - # Instantiates the Generator + # Instantiates the Generator. def build_generator(name, params) Rails::Generator::Base.instance(name, params) end - # Runs the create command (like the command line does) + # Runs the +create+ command (like the command line does). def run_generator(name, params) silence_generator do build_generator(name, params).command(:create).invoke! end end - # Silences the logger temporarily and returns the output as a String + # Silences the logger temporarily and returns the output as a String. def silence_generator logger_original = Rails::Generator::Base.logger myout = StringIO.new @@ -108,7 +108,7 @@ class GeneratorTestCase < Test::Unit::TestCase myout.string end - # asserts that the given controller was generated. + # Asserts that the given controller was generated. # It takes a name or symbol without the <tt>_controller</tt> part and an optional super class. # The contents of the class source file is passed to a block. def assert_generated_controller_for(name, parent = "ApplicationController") @@ -117,44 +117,44 @@ class GeneratorTestCase < Test::Unit::TestCase end end - # asserts that the given model was generated. + # Asserts that the given model was generated. # It takes a name or symbol and an optional super class. - # the contents of the class source file is passed to a block. + # The contents of the class source file is passed to a block. def assert_generated_model_for(name, parent = "ActiveRecord::Base") assert_generated_class "app/models/#{name.to_s.underscore}", parent do |body| yield body if block_given? end end - # asserts that the given helper was generated. - # It takes a name or symbol without the <tt>_helper</tt> part - # the contents of the module source file is passed to a block. + # Asserts that the given helper was generated. + # It takes a name or symbol without the <tt>_helper</tt> part. + # The contents of the module source file is passed to a block. def assert_generated_helper_for(name) assert_generated_module "app/helpers/#{name.to_s.underscore}_helper" do |body| yield body if block_given? end end - # asserts that the given functional test was generated. + # Asserts that the given functional test was generated. # It takes a name or symbol without the <tt>_controller_test</tt> part and an optional super class. - # the contents of the class source file is passed to a block. + # The contents of the class source file is passed to a block. def assert_generated_functional_test_for(name, parent = "ActionController::TestCase") assert_generated_class "test/functional/#{name.to_s.underscore}_controller_test",parent do |body| yield body if block_given? end end - # asserts that the given unit test was generated. + # Asserts that the given unit test was generated. # It takes a name or symbol without the <tt>_test</tt> part and an optional super class. - # the contents of the class source file is passed to a block. + # The contents of the class source file is passed to a block. def assert_generated_unit_test_for(name, parent = "ActiveSupport::TestCase") assert_generated_class "test/unit/#{name.to_s.underscore}_test", parent do |body| yield body if block_given? end end - # asserts that the given file was generated. - # the contents of the file is passed to a block. + # Asserts that the given file was generated. + # The contents of the file is passed to a block. def assert_generated_file(path) assert_file_exists(path) File.open("#{RAILS_ROOT}/#{path}") do |f| @@ -168,9 +168,9 @@ class GeneratorTestCase < Test::Unit::TestCase "The file '#{RAILS_ROOT}/#{path}' should exist" end - # asserts that the given class source file was generated. + # Asserts that the given class source file was generated. # It takes a path without the <tt>.rb</tt> part and an optional super class. - # the contents of the class source file is passed to a block. + # The contents of the class source file is passed to a block. def assert_generated_class(path, parent = nil) # FIXME: Sucky way to detect namespaced classes if path.split('/').size > 3 @@ -187,9 +187,9 @@ class GeneratorTestCase < Test::Unit::TestCase end end - # asserts that the given module source file was generated. + # Asserts that the given module source file was generated. # It takes a path without the <tt>.rb</tt> part. - # the contents of the class source file is passed to a block. + # The contents of the class source file is passed to a block. def assert_generated_module(path) # FIXME: Sucky way to detect namespaced modules if path.split('/').size > 3 @@ -206,18 +206,18 @@ class GeneratorTestCase < Test::Unit::TestCase end end - # asserts that the given css stylesheet file was generated. + # Asserts that the given CSS stylesheet file was generated. # It takes a path without the <tt>.css</tt> part. - # the contents of the stylesheet source file is passed to a block. + # The contents of the stylesheet source file is passed to a block. def assert_generated_stylesheet(path) assert_generated_file("public/stylesheets/#{path}.css") do |body| yield body if block_given? end end - # asserts that the given yaml file was generated. + # Asserts that the given YAML file was generated. # It takes a path without the <tt>.yml</tt> part. - # the parsed yaml tree is passed to a block. + # The parsed YAML tree is passed to a block. def assert_generated_yaml(path) assert_generated_file("#{path}.yml") do |body| yaml = YAML.load(body) @@ -226,18 +226,18 @@ class GeneratorTestCase < Test::Unit::TestCase end end - # asserts that the given fixtures yaml file was generated. + # Asserts that the given fixtures yaml file was generated. # It takes a fixture name without the <tt>.yml</tt> part. - # the parsed yaml tree is passed to a block. + # The parsed YAML tree is passed to a block. def assert_generated_fixtures_for(name) assert_generated_yaml "test/fixtures/#{name.to_s.underscore}" do |yaml| yield yaml if block_given? end end - # asserts that the given views were generated. + # Asserts that the given views were generated. # It takes a controller name and a list of views (including extensions). - # The body of each view is passed to a block + # The body of each view is passed to a block. def assert_generated_views_for(name, *actions) actions.each do |action| assert_generated_file("app/views/#{name.to_s.underscore}/#{action}") do |body| @@ -262,7 +262,7 @@ class GeneratorTestCase < Test::Unit::TestCase assert !File.exist?(migration_file), "should not create migration #{migration_file}" end - # asserts that the given resource was added to the routes. + # Asserts that the given resource was added to the routes. def assert_added_route_for(name) assert_generated_file("config/routes.rb") do |body| assert_match /map.resources :#{name.to_s.underscore}/, body, @@ -270,7 +270,7 @@ class GeneratorTestCase < Test::Unit::TestCase end end - # asserts that the given methods are defined in the body. + # Asserts that the given methods are defined in the body. # This does assume standard rails code conventions with regards to the source code. # The body of each individual method is passed to a block. def assert_has_method(body, *methods) @@ -280,7 +280,7 @@ class GeneratorTestCase < Test::Unit::TestCase end end - # asserts that the given column is defined in the migration + # Asserts that the given column is defined in the migration. def assert_generated_column(body, name, type) assert_match /t\.#{type.to_s} :#{name.to_s}/, body, "should have column #{name.to_s} defined" end |