Permalink
Browse files

Merge docrails.

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>
  • Loading branch information...
1 parent 6277fd9 commit 98dc582742779081e71e697fcdf8d9ae2b421b16 @lifo lifo committed May 25, 2008
Showing with 886 additions and 778 deletions.
  1. +7 −7 actionmailer/lib/action_mailer/base.rb
  2. +1 −1 actionmailer/lib/action_mailer/helpers.rb
  3. +2 −2 actionmailer/lib/action_mailer/part.rb
  4. +2 −1 actionpack/lib/action_controller/assertions/model_assertions.rb
  5. +3 −3 actionpack/lib/action_controller/assertions/routing_assertions.rb
  6. +13 −13 actionpack/lib/action_controller/assertions/selector_assertions.rb
  7. +3 −3 actionpack/lib/action_controller/assertions/tag_assertions.rb
  8. +7 −7 actionpack/lib/action_controller/base.rb
  9. +17 −18 actionpack/lib/action_controller/cgi_ext/cookie.rb
  10. +1 −1 actionpack/lib/action_controller/cgi_process.rb
  11. +20 −20 actionpack/lib/action_controller/filters.rb
  12. +7 −7 actionpack/lib/action_controller/helpers.rb
  13. +9 −9 actionpack/lib/action_controller/integration.rb
  14. +2 −2 actionpack/lib/action_controller/mime_type.rb
  15. +6 −7 actionpack/lib/action_controller/polymorphic_routes.rb
  16. +3 −3 actionpack/lib/action_controller/resources.rb
  17. +3 −3 actionpack/lib/action_controller/routing/builder.rb
  18. +1 −1 actionpack/lib/action_controller/session/cookie_store.rb
  19. +2 −2 actionpack/lib/action_controller/test_process.rb
  20. +12 −12 actionpack/lib/action_view/helpers/asset_tag_helper.rb
  21. +57 −38 actionpack/lib/action_view/helpers/form_helper.rb
  22. +19 −21 actionpack/lib/action_view/helpers/form_options_helper.rb
  23. +4 −4 actionpack/lib/action_view/helpers/form_tag_helper.rb
  24. +4 −4 actionpack/lib/action_view/helpers/prototype_helper.rb
  25. +2 −2 actionpack/lib/action_view/helpers/record_tag_helper.rb
  26. +16 −15 actionpack/lib/action_view/helpers/sanitize_helper.rb
  27. +79 −84 actionpack/lib/action_view/helpers/scriptaculous_helper.rb
  28. +1 −1 actionpack/lib/action_view/helpers/url_helper.rb
  29. +2 −2 actionpack/lib/action_view/template.rb
  30. +9 −9 activerecord/lib/active_record/aggregations.rb
  31. +67 −57 activerecord/lib/active_record/associations.rb
  32. +2 −2 activerecord/lib/active_record/associations/association_collection.rb
  33. +1 −1 activerecord/lib/active_record/associations/has_many_through_association.rb
  34. +5 −5 activerecord/lib/active_record/attribute_methods.rb
  35. +113 −101 activerecord/lib/active_record/base.rb
  36. +12 −10 activerecord/lib/active_record/calculations.rb
  37. +1 −1 activerecord/lib/active_record/callbacks.rb
  38. +1 −1 activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
  39. +2 −2 activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
  40. +16 −16 activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
  41. +1 −1 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
  42. +1 −1 activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
  43. +25 −24 activerecord/lib/active_record/fixtures.rb
  44. +7 −7 activerecord/lib/active_record/locking/optimistic.rb
  45. +2 −2 activerecord/lib/active_record/migration.rb
  46. +2 −4 activerecord/lib/active_record/named_scope.rb
  47. +2 −2 activerecord/lib/active_record/observer.rb
  48. +2 −2 activerecord/lib/active_record/schema.rb
  49. +1 −1 activerecord/lib/active_record/schema_dumper.rb
  50. +3 −3 activerecord/lib/active_record/serializers/xml_serializer.rb
  51. +2 −2 activerecord/lib/active_record/transactions.rb
  52. +2 −2 activerecord/lib/active_record/validations.rb
  53. +16 −16 activeresource/lib/active_resource/base.rb
  54. +7 −7 activeresource/lib/active_resource/custom_methods.rb
  55. +1 −1 activeresource/lib/active_resource/formats/xml_format.rb
  56. +74 −3 activeresource/lib/active_resource/http_mock.rb
  57. +2 −2 activeresource/lib/active_resource/validations.rb
  58. +1 −1 activesupport/lib/active_support/core_ext/hash/conversions.rb
  59. +8 −4 activesupport/lib/active_support/core_ext/integer/even_odd.rb
  60. +1 −1 activesupport/lib/active_support/core_ext/object/misc.rb
  61. +5 −5 activesupport/lib/active_support/core_ext/string/unicode.rb
  62. +1 −1 activesupport/lib/active_support/core_ext/time/conversions.rb
  63. +12 −12 activesupport/lib/active_support/core_ext/time/zones.rb
  64. +2 −2 activesupport/lib/active_support/deprecation.rb
  65. +59 −59 activesupport/lib/active_support/inflector.rb
  66. +1 −1 activesupport/lib/active_support/json.rb
  67. +1 −1 activesupport/lib/active_support/json/decoding.rb
  68. +1 −1 activesupport/lib/active_support/multibyte/chars.rb
  69. +8 −10 activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
  70. +17 −17 activesupport/lib/active_support/time_with_zone.rb
  71. +7 −7 activesupport/lib/active_support/values/time_zone.rb
  72. +2 −2 railties/configs/databases/frontbase.yml
  73. +2 −2 railties/configs/databases/mysql.yml
  74. +3 −3 railties/configs/databases/oracle.yml
  75. +2 −2 railties/configs/databases/postgresql.yml
  76. +2 −2 railties/configs/databases/sqlite2.yml
  77. +2 −2 railties/configs/databases/sqlite3.yml
  78. +4 −4 railties/configs/initializers/new_rails_defaults.rb
  79. +4 −4 railties/environments/environment.rb
  80. +1 −1 railties/environments/test.rb
  81. +23 −23 railties/lib/initializer.rb
  82. +1 −1 railties/lib/rails_generator/base.rb
  83. +1 −1 railties/lib/tasks/databases.rake
  84. +1 −1 railties/test/fixtures/about_yml_plugins/bad_about_yml/about.yml
  85. +30 −30 railties/test/generators/generator_test_helper.rb
@@ -5,12 +5,12 @@
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 @@ def method_missing(method_symbol, *parameters)#: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 @@ def create!(method_name, *parameters) #: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
@@ -34,7 +34,7 @@ def add_template_helper(helper_module) #:nodoc:
# 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)
@@ -5,15 +5,15 @@
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
include ActionMailer::PartContainer
# 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
@@ -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
#
@@ -59,7 +59,7 @@ def assert_recognizes(expected_options, path, extras={}, message=nil)
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 @@ def assert_generates(expected_path, options, defaults={}, extras = {}, message=n
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.
@@ -12,12 +12,12 @@ module Assertions
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 SelectorAssertions
# 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 @@ def css_select(*args)
# 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 @@ def css_select(*args)
# 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 @@ def count_description(min, max) #:nodoc:
#
# === 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 @@ def assert_select_email(&block)
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
@@ -91,7 +91,7 @@ module TagAssertions
# :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 @@ def assert_tag(*opts)
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"
@@ -104,7 +104,7 @@ class UnknownHttpMethod < ActionControllerError #: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 @@ class UnknownHttpMethod < ActionControllerError #: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 @@ class Base
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 @@ class Base
#
# 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] =
@@ -6,25 +6,24 @@ class Cookie < DelegateClass(Array)
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 @@ def initialize(name = '', *value)
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 @@ def to_s
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([])
@@ -15,7 +15,7 @@ class Base
# * <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.
Oops, something went wrong.

6 comments on commit 98dc582

@adamsalter

Ummm…
Mostly good doc info, but I think changing “ActionMailer” to “Action Mailer” is misleading… The class is called “ActionMailer”, so references to “an Action Mailer instance” is spurious. As a practical consideration searches for “ActionMailer” will no longer match.

Likewise for all the other “Active Resource”, “Action Controller” etc. changes.

-1 for those changes.

@josh
Member
josh commented on 98dc582 May 26, 2008

I agree w/ Adam

@jeremy
Member
jeremy commented on 98dc582 May 26, 2008

Most of the changes here refer to the frameworks by name, not Ruby classes or instances, and the wording reads better.

Those changing “ActiveRecord object” to “Active Record object” and similar are wrong, though. They’re really over-wordy in the first place, too: ActiveRecord objects are records; ActiveResource objects are resources. How about tightening up that language overall?

@fxn
Member
fxn commented on 98dc582 May 26, 2008

The docs were not consistent in the usage of these names, a choice was needed.

AWDwR uses spaces, and The Rails Way does not. So I asked David on the IRC and he said the proper name of the Rails components have spaces. That is, Active Record is the ORM, and ActiveRecord is the module. The docs were revised and the convention documented in the wiki.

@fxn
Member
fxn commented on 98dc582 May 26, 2008

Oh, I do agree that the ones involving instances may need a second pass. On the one hand ActiveRecord has no instances, ActiveRecord::Base does. On the other hand we say ARs informally. We could just say “models” and “mailers”….

@fxn
Member
fxn commented on 98dc582 May 26, 2008

Oh, I do agree that the ones involving instances may need a second pass. On the one hand ActiveRecord has no instances, ActiveRecord::Base does. On the other hand we say ARs informally. We could just say “models” and “mailers”….

Please sign in to comment.