Permalink
Browse files

Improve documentation coverage and markup

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>
  • Loading branch information...
1 parent 87ec72b commit 64092de25727c1943807bf5345107d90428135a0 @fxn fxn committed with lifo May 2, 2008
Showing with 811 additions and 659 deletions.
  1. +6 −6 actionmailer/lib/action_mailer/base.rb
  2. +7 −6 actionpack/lib/action_controller/base.rb
  3. +31 −19 actionpack/lib/action_controller/cookies.rb
  4. +5 −4 actionpack/lib/action_controller/filters.rb
  5. +10 −2 actionpack/lib/action_controller/helpers.rb
  6. +1 −1 actionpack/lib/action_controller/polymorphic_routes.rb
  7. +9 −9 actionpack/lib/action_controller/request.rb
  8. +2 −1 actionpack/lib/action_controller/request_forgery_protection.rb
  9. +19 −17 actionpack/lib/action_controller/rescue.rb
  10. +7 −7 actionpack/lib/action_controller/resources.rb
  11. +49 −45 actionpack/lib/action_controller/routing.rb
  12. +2 −2 actionpack/lib/action_controller/routing/builder.rb
  13. +10 −9 actionpack/lib/action_controller/routing/optimisations.rb
  14. +2 −2 actionpack/lib/action_controller/routing/route.rb
  15. +13 −13 actionpack/lib/action_controller/session/cookie_store.rb
  16. +5 −3 actionpack/lib/action_controller/session_management.rb
  17. +15 −9 actionpack/lib/action_controller/streaming.rb
  18. +33 −31 actionpack/lib/action_controller/test_process.rb
  19. +10 −7 actionpack/lib/action_controller/url_rewriter.rb
  20. +3 −2 actionpack/lib/action_view/base.rb
  21. +69 −55 actionpack/lib/action_view/helpers/active_record_helper.rb
  22. +2 −2 actionpack/lib/action_view/helpers/asset_tag_helper.rb
  23. +4 −4 actionpack/lib/action_view/helpers/date_helper.rb
  24. +1 −1 actionpack/lib/action_view/helpers/form_helper.rb
  25. +2 −2 actionpack/lib/action_view/helpers/form_options_helper.rb
  26. +3 −2 actionpack/lib/action_view/helpers/form_tag_helper.rb
  27. +10 −10 actionpack/lib/action_view/helpers/prototype_helper.rb
  28. +2 −2 actionpack/lib/action_view/helpers/sanitize_helper.rb
  29. +2 −2 actionpack/lib/action_view/helpers/scriptaculous_helper.rb
  30. +8 −8 actionpack/lib/action_view/helpers/url_helper.rb
  31. +1 −1 actionpack/lib/action_view/partials.rb
  32. +10 −10 activemodel/lib/active_model/validations.rb
  33. +13 −13 activemodel/lib/active_model/validations/acceptance.rb
  34. +7 −7 activemodel/lib/active_model/validations/associated.rb
  35. +8 −8 activemodel/lib/active_model/validations/confirmation.rb
  36. +8 −8 activemodel/lib/active_model/validations/exclusion.rb
  37. +10 −10 activemodel/lib/active_model/validations/format.rb
  38. +8 −8 activemodel/lib/active_model/validations/inclusion.rb
  39. +21 −22 activemodel/lib/active_model/validations/length.rb
  40. +16 −16 activemodel/lib/active_model/validations/numericality.rb
  41. +15 −11 activemodel/lib/active_model/validations/presence.rb
  42. +9 −9 activemodel/lib/active_model/validations/uniqueness.rb
  43. +10 −0 activerecord/lib/active_record/associations/association_proxy.rb
  44. +32 −36 activerecord/lib/active_record/base.rb
  45. +6 −6 activerecord/lib/active_record/calculations.rb
  46. +2 −1 activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
  47. +2 −2 activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
  48. +1 −1 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
  49. +1 −1 activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
  50. +4 −4 activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
  51. +2 −2 activerecord/lib/active_record/locking/pessimistic.rb
  52. +4 −4 activerecord/lib/active_record/migration.rb
  53. +7 −8 activerecord/lib/active_record/reflection.rb
  54. +5 −5 activerecord/lib/active_record/serialization.rb
  55. +4 −4 activerecord/lib/active_record/serializers/json_serializer.rb
  56. +15 −15 activerecord/lib/active_record/serializers/xml_serializer.rb
  57. +108 −108 activerecord/lib/active_record/validations.rb
  58. +6 −5 activeresource/lib/active_resource/base.rb
  59. +2 −2 activeresource/lib/active_resource/connection.rb
  60. +1 −1 activesupport/lib/active_support/cache.rb
  61. +43 −8 activesupport/lib/active_support/core_ext/array/conversions.rb
  62. +7 −1 activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
  63. +1 −1 activesupport/lib/active_support/core_ext/date/calculations.rb
  64. +4 −2 activesupport/lib/active_support/core_ext/date_time/calculations.rb
  65. +11 −10 activesupport/lib/active_support/core_ext/enumerable.rb
  66. +1 −1 activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
  67. +11 −1 activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
  68. +5 −3 activesupport/lib/active_support/core_ext/module/delegation.rb
  69. +8 −0 activesupport/lib/active_support/core_ext/range/include_range.rb
  70. +3 −0 activesupport/lib/active_support/core_ext/range/overlaps.rb
  71. +6 −4 activesupport/lib/active_support/core_ext/time/calculations.rb
  72. +19 −8 activesupport/lib/active_support/inflector.rb
  73. +3 −1 activesupport/lib/active_support/multibyte/handlers/utf8_handler.rb
  74. +7 −6 activesupport/lib/active_support/time_with_zone.rb
  75. +2 −2 railties/lib/initializer.rb
@@ -198,31 +198,31 @@ module ActionMailer #:nodoc:
#
# These options are specified on the class level, like <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
#
- # * <tt>template_root</tt> - template root determines the base from which template references will be made.
+ # * <tt>template_root</tt> - Determines the base from which template references will be made.
#
# * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
# Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
#
- # * <tt>smtp_settings</tt> - Allows detailed configuration for :smtp delivery method:
+ # * <tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt> delivery method:
# * <tt>:address</tt> Allows you to use a remote mail server. Just change it from its default "localhost" setting.
# * <tt>:port</tt> On the off chance that your mail server doesn't run on port 25, you can change it.
# * <tt>:domain</tt> If you need to specify a HELO domain, you can do it here.
# * <tt>:user_name</tt> If your mail server requires authentication, set the username in this setting.
# * <tt>:password</tt> If your mail server requires authentication, set the password in this setting.
# * <tt>:authentication</tt> If your mail server requires authentication, you need to specify the authentication type here.
- # This is a symbol and one of :plain, :login, :cram_md5
+ # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>
#
- # * <tt>sendmail_settings</tt> - Allows you to override options for the :sendmail delivery method
+ # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method
# * <tt>:location</tt> The location of the sendmail executable, defaults to "/usr/sbin/sendmail"
# * <tt>:arguments</tt> The command line arguments
# * <tt>raise_delivery_errors</tt> - whether or not errors should be raised if the email fails to be delivered.
#
- # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are :smtp (default), :sendmail, and :test.
+ # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>.
#
# * <tt>perform_deliveries</tt> - Determines whether deliver_* methods are actually carried out. By default they are,
# but this can be turned off to help functional testing.
#
- # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful
+ # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with <tt>delivery_method :test</tt>. Most useful
# for unit and functional testing.
#
# * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
@@ -332,7 +332,8 @@ class Base
@@resources_path_names = { :new => 'new', :edit => 'edit' }
cattr_accessor :resources_path_names
- # Sets the token parameter name for RequestForgery. Calling #protect_from_forgery sets it to :authenticity_token by default
+ # Sets the token parameter name for RequestForgery. Calling +protect_from_forgery+
+ # sets it to <tt>:authenticity_token</tt> by default.
cattr_accessor :request_forgery_protection_token
# Indicates whether or not optimise the generated named
@@ -544,8 +545,8 @@ def process(request, response, method = :perform_action, *arguments) #:nodoc:
# * <tt>:host</tt> -- overrides the default (current) host if provided.
# * <tt>:protocol</tt> -- overrides the default (current) protocol if provided.
# * <tt>:port</tt> -- optionally specify the port to connect to.
- # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if :password is also present).
- # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if :user is also present).
+ # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present).
+ # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present).
# * <tt>:skip_relative_url_root</tt> -- if true, the url is not constructed using the relative_url_root of the request so the path
# will include the web server relative installation directory.
#
@@ -598,7 +599,7 @@ def process(request, response, method = :perform_action, *arguments) #:nodoc:
# url_for :controller => 'posts', :action => nil
#
# If you explicitly want to create a URL that's almost the same as the current URL, you can do so using the
- # :overwrite_params options. Say for your posts you have different views for showing and printing them.
+ # <tt>:overwrite_params</tt> options. Say for your posts you have different views for showing and printing them.
# Then, in the show view, you get the URL for the print view like this
#
# url_for :overwrite_params => { :action => 'print' }
@@ -769,7 +770,7 @@ def append_view_path(path)
# # placed in "app/views/layouts/special.r(html|xml)"
# render :text => "Hi there!", :layout => "special"
#
- # The :text option can also accept a Proc object, which can be used to manually control the page generation. This should
+ # The <tt>:text</tt> option can also accept a Proc object, which can be used to manually control the page generation. This should
# generally be avoided, as it violates the separation between code and content, and because almost everything that can be
# done with this method can also be done more cleanly using one of the other rendering methods, most notably templates.
#
@@ -823,7 +824,7 @@ def append_view_path(path)
#
# === Rendering with status and location headers
#
- # All renders take the :status and :location options and turn them into headers. They can even be used together:
+ # All renders take the <tt>:status</tt> and <tt>:location</tt> options and turn them into headers. They can even be used together:
#
# render :xml => post.to_xml, :status => :created, :location => post_url(post)
def render(options = nil, extra_options = {}, &block) #:doc:
@@ -1,31 +1,38 @@
module ActionController #:nodoc:
- # Cookies are read and written through ActionController#cookies. The cookies being read are what were received along with the request,
- # the cookies being written are what will be sent out with the response. Cookies are read by value (so you won't get the cookie object
- # itself back -- just the value it holds). Examples for writing:
+ # Cookies are read and written through ActionController#cookies.
#
- # cookies[:user_name] = "david" # => Will set a simple session cookie
+ # The cookies being read are the ones received along with the request, the cookies
+ # being written will be sent out with the response. Reading a cookie does not get
+ # the cookie object itself back, just the value it holds.
+ #
+ # Examples for writing:
+ #
+ # # Sets a simple session cookie.
+ # cookies[:user_name] = "david"
+ #
+ # # Sets a cookie that expires in 1 hour.
# cookies[:login] = { :value => "XJ-122", :expires => 1.hour.from_now }
- # # => Will set a cookie that expires in 1 hour
#
# Examples for reading:
#
# cookies[:user_name] # => "david"
- # cookies.size # => 2
+ # cookies.size # => 2
#
# Example for deleting:
#
# cookies.delete :user_name
#
- # All the option symbols for setting cookies are:
+ # The option symbols for setting cookies are:
#
- # * <tt>value</tt> - the cookie's value or list of values (as an array).
- # * <tt>path</tt> - the path for which this cookie applies. Defaults to the root of the application.
- # * <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 (default to false).
- # Secure cookies are only transmitted to HTTPS servers.
- # * <tt>http_only</tt> - whether this cookie is accessible via scripting or only HTTP (defaults to false).
-
+ # * <tt>:value</tt> - The cookie's value or list of values (as an array).
+ # * <tt>:path</tt> - The path for which this cookie applies. Defaults to the root
+ # of the application.
+ # * <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 only transmitted to HTTPS servers.
+ # Default is +false+.
+ # * <tt>:http_only</tt> - Whether this cookie is accessible via scripting or
+ # only HTTP. Defaults to +false+.
module Cookies
def self.included(base)
base.helper_method :cookies
@@ -45,15 +52,16 @@ def initialize(controller)
update(@cookies)
end
- # Returns the value of the cookie by +name+ -- or nil if no such cookie exists. You set new cookies using cookies[]=
- # (for simple name/value cookies without options).
+ # Returns the value of the cookie by +name+, or +nil+ if no such cookie exists.
def [](name)
cookie = @cookies[name.to_s]
if cookie && cookie.respond_to?(:value)
cookie.size > 1 ? cookie.value : cookie.value[0]
end
end
+ # Sets the cookie named +name+. The second argument may be the very cookie
+ # value, or a hash of options as documented above.
def []=(name, options)
if options.is_a?(Hash)
options = options.inject({}) { |options, pair| options[pair.first.to_s] = pair.last; options }
@@ -66,14 +74,18 @@ def []=(name, options)
end
# Removes the cookie on the client machine by setting the value to an empty string
- # and setting its expiration date into the past. Like []=, you can pass in an options
- # hash to delete cookies with extra data such as a +path+.
+ # and setting its expiration date into the past. Like <tt>[]=</tt>, you can pass in
+ # an options hash to delete cookies with extra data such as a <tt>:path</tt>.
def delete(name, options = {})
options.stringify_keys!
set_cookie(options.merge("name" => name.to_s, "value" => "", "expires" => Time.at(0)))
end
private
+ # Builds a CGI::Cookie object and adds the cookie to the response headers.
+ #
+ # The path of the cookie defaults to "/" if there's none in +options+, and
+ # everything is passed to the CGI::Cookie constructor.
def set_cookie(options) #:doc:
options["path"] = "/" unless options["path"]
cookie = CGI::Cookie.new(options)
@@ -126,8 +126,8 @@ def self.included(base)
# end
#
# To use a filter object with around_filter, pass an object responding
- # to :filter or both :before and :after. With a filter method, yield to
- # the block as above:
+ # to <tt>:filter</tt> or both <tt>:before</tt> and <tt>:after</tt>. With a
+ # filter method, yield to the block as above:
#
# around_filter BenchmarkingFilter
#
@@ -191,8 +191,9 @@ def self.included(base)
# == Filter conditions
#
# Filters may be limited to specific actions by declaring the actions to
- # include or exclude. Both options accept single actions (:only => :index)
- # or arrays of actions (:except => [:foo, :bar]).
+ # include or exclude. Both options accept single actions
+ # (<tt>:only => :index</tt>) or arrays of actions
+ # (<tt>:except => [:foo, :bar]</tt>).
#
# class Journal < ActionController::Base
# # Require authentication for edit and delete.
@@ -143,11 +143,19 @@ def helper(*args, &block)
# Declare a controller method as a helper. For example, the following
# makes the +current_user+ controller method available to the view:
# class ApplicationController < ActionController::Base
- # helper_method :current_user
+ # helper_method :current_user, :logged_in?
+ #
# def current_user
- # @current_user ||= User.find(session[:user])
+ # @current_user ||= User.find_by_id(session[:user])
# end
+ #
+ # def logged_in?
+ # current_user != nil
+ # end
# end
+ #
+ # In a view:
+ # <% if logged_in? -%>Welcome, <%= current_user.name %><% end -%>
def helper_method(*methods)
methods.flatten.each do |method|
master_helper_module.module_eval <<-end_eval
@@ -19,7 +19,7 @@ module ActionController
# * <tt>url_for</tt>, so you can use it with a record as the argument, e.g.
# <tt>url_for(@article)</tt>;
# * ActionView::Helpers::FormHelper uses <tt>polymorphic_path</tt>, so you can write
- # <tt>form_for(@article)</tt> without having to specify :url parameter for the form
+ # <tt>form_for(@article)</tt> without having to specify <tt>:url</tt> parameter for the form
# action;
# * <tt>redirect_to</tt> (which, in fact, uses <tt>url_for</tt>) so you can write
# <tt>redirect_to(post)</tt> in your controllers;
@@ -15,7 +15,7 @@ class AbstractRequest
# such as { 'RAILS_ENV' => 'production' }.
attr_reader :env
- # The true HTTP request method as a lowercase symbol, such as :get.
+ # The true HTTP request method as a lowercase symbol, such as <tt>:get</tt>.
# UnknownHttpMethod is raised for invalid methods not listed in ACCEPTED_HTTP_METHODS.
def request_method
@request_method ||= begin
@@ -28,35 +28,35 @@ def request_method
end
end
- # The HTTP request method as a lowercase symbol, such as :get.
- # Note, HEAD is returned as :get since the two are functionally
+ # The HTTP request method as a lowercase symbol, such as <tt>:get</tt>.
+ # Note, HEAD is returned as <tt>:get</tt> since the two are functionally
# equivalent from the application's perspective.
def method
request_method == :head ? :get : request_method
end
- # Is this a GET (or HEAD) request? Equivalent to request.method == :get
+ # Is this a GET (or HEAD) request? Equivalent to <tt>request.method == :get</tt>.
def get?
method == :get
end
- # Is this a POST request? Equivalent to request.method == :post
+ # Is this a POST request? Equivalent to <tt>request.method == :post</tt>.
def post?
request_method == :post
end
- # Is this a PUT request? Equivalent to request.method == :put
+ # Is this a PUT request? Equivalent to <tt>request.method == :put</tt>.
def put?
request_method == :put
end
- # Is this a DELETE request? Equivalent to request.method == :delete
+ # Is this a DELETE request? Equivalent to <tt>request.method == :delete</tt>.
def delete?
request_method == :delete
end
- # Is this a HEAD request? request.method sees HEAD as :get, so check the
- # HTTP method directly.
+ # Is this a HEAD request? <tt>request.method</tt> sees HEAD as <tt>:get</tt>,
+ # so check the HTTP method directly.
def head?
request_method == :head
end
@@ -102,7 +102,8 @@ def verifiable_request_format?
request.format.html? || request.format.js?
end
- # Sets the token value for the current session. Pass a :secret option in #protect_from_forgery to add a custom salt to the hash.
+ # Sets the token value for the current session. Pass a <tt>:secret</tt> option
+ # in +protect_from_forgery+ to add a custom salt to the hash.
def form_authenticity_token
@form_authenticity_token ||= if request_forgery_protection_options[:secret]
authenticity_token_from_session_id
@@ -58,33 +58,35 @@ def process_with_exception(request, response, exception) #:nodoc:
# Rescue exceptions raised in controller actions.
#
# <tt>rescue_from</tt> receives a series of exception classes or class
- # names, and a trailing :with option with the name of a method or a Proc
- # object to be called to handle them. Alternatively a block can be given.
+ # names, and a trailing <tt>:with</tt> option with the name of a method
+ # or a Proc object to be called to handle them. Alternatively a block can
+ # be given.
#
# Handlers that take one argument will be called with the exception, so
# that the exception can be inspected when dealing with it.
#
# Handlers are inherited. They are searched from right to left, from
# bottom to top, and up the hierarchy. The handler of the first class for
- # which exception.is_a?(klass) holds true is the one invoked, if any.
+ # which <tt>exception.is_a?(klass)</tt> holds true is the one invoked, if
+ # any.
#
- # class ApplicationController < ActionController::Base
- # rescue_from User::NotAuthorized, :with => :deny_access # self defined exception
- # rescue_from ActiveRecord::RecordInvalid, :with => :show_errors
+ # class ApplicationController < ActionController::Base
+ # rescue_from User::NotAuthorized, :with => :deny_access # self defined exception
+ # rescue_from ActiveRecord::RecordInvalid, :with => :show_errors
#
- # rescue_from 'MyAppError::Base' do |exception|
- # render :xml => exception, :status => 500
- # end
- #
- # protected
- # def deny_access
- # ...
+ # rescue_from 'MyAppError::Base' do |exception|
+ # render :xml => exception, :status => 500
# end
#
- # def show_errors(exception)
- # exception.record.new_record? ? ...
- # end
- # end
+ # protected
+ # def deny_access
+ # ...
+ # end
+ #
+ # def show_errors(exception)
+ # exception.record.new_record? ? ...
+ # end
+ # end
def rescue_from(*klasses, &block)
options = klasses.extract_options!
unless options.has_key?(:with)
Oops, something went wrong.

0 comments on commit 64092de

Please sign in to comment.