Merge branch 'master' of git://github.com/lifo/docrails

jnovak · May 4, 2011 · cea3b3c · cea3b3c
2 parents 897318f + 24586ed
commit cea3b3c
Show file tree

Hide file tree

Showing 12 changed files with 82 additions and 97 deletions.
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
@@ -83,7 +83,7 @@ module ActiveRecord #:nodoc:
   #
   # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query
   # and is thus susceptible to SQL-injection attacks if the <tt>user_name</tt> and +password+
-  # parameters come directly from an HTTP request. The <tt>authenticate_safely</tt>  and
+  # parameters come directly from an HTTP request. The <tt>authenticate_safely</tt> and
   # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+
   # before inserting them in the query, which will ensure that an attacker can't escape the
   # query and fake the login (or worse).
@@ -406,10 +406,10 @@ class Base
     ##
     # :singleton-method:
     # Specifies the format to use when dumping the database schema with Rails'
-    # Rakefile.  If :sql, the schema is dumped as (potentially database-
-    # specific) SQL statements.  If :ruby, the schema is dumped as an
+    # Rakefile. If :sql, the schema is dumped as (potentially database-
+    # specific) SQL statements. If :ruby, the schema is dumped as an
     # ActiveRecord::Schema file which can be loaded into any database that
-    # supports migrations.  Use :ruby if you want to have different database
+    # supports migrations. Use :ruby if you want to have different database
     # adapters for, e.g., your development and test environments.
     cattr_accessor :schema_format , :instance_writer => false
     @@schema_format = :ruby
@@ -443,17 +443,17 @@ class << self # Class methods
       delegate :select, :group, :order, :except, :reorder, :limit, :offset, :joins, :where, :preload, :eager_load, :includes, :from, :lock, :readonly, :having, :create_with, :to => :scoped
       delegate :count, :average, :minimum, :maximum, :sum, :calculate, :to => :scoped
 
-      # 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 <tt>Product.find_by_sql</tt> then the results will be returned in
+      # this method from. If you call <tt>Product.find_by_sql</tt> then the results will be returned in
       # a Product object with the attributes you specified in the SQL query.
       #
       # If you call a complicated SQL query which spans multiple tables the columns specified by the
       # 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
-      # no database agnostic conversions performed.  This should be a last resort because using, for example,
+      # 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.
       #
@@ -472,7 +472,7 @@ def find_by_sql(sql, binds = [])
       # Creates an object (or multiple objects) and saves it to the database, if validations pass.
       # The resulting object is returned whether the object was saved successfully to the database or not.
       #
-      # The +attributes+ parameter can be either be a Hash or an Array of Hashes.  These Hashes describe the
+      # The +attributes+ parameter can be either be a Hash or an Array of Hashes. These Hashes describe the
       # attributes on the objects that are to be created.
       #
       # +create+ respects mass-assignment security and accepts either +:as+ or +:without_protection+ options
@@ -513,7 +513,7 @@ def create(attributes = nil, options = {}, &block)
 
       # Returns the result of an SQL statement that should only include a COUNT(*) in the SELECT part.
       # The use of this method should be restricted to complicated SQL queries that can't be executed
-      # using the ActiveRecord::Calculations class methods.  Look into those before using this.
+      # using the ActiveRecord::Calculations class methods. Look into those before using this.
       #
       # ==== Parameters
       #
@@ -590,7 +590,7 @@ def serialize(attr_name, class_name = Object)
       #   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,
+      # +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".
       #
@@ -624,7 +624,7 @@ def inheritance_column
         @inheritance_column ||= "type"
       end
 
-      # Lazy-set the sequence name to the connection's default.  This method
+      # Lazy-set the sequence name to the connection's default. This method
       # is only ever called once since set_sequence_name overrides it.
       def sequence_name #:nodoc:
         reset_sequence_name
@@ -636,7 +636,7 @@ def reset_sequence_name #:nodoc:
         default
       end
 
-      # Sets the table name. If the value is nil or false  then the value returned by the given
+      # Sets the table name. If the value is nil or false then the value returned by the given
       # block is used.
       #
       #   class Project < ActiveRecord::Base
@@ -1086,7 +1086,7 @@ def all_attributes_exists?(attribute_names)
         # <tt>where</tt>, <tt>includes</tt>, and <tt>joins</tt> operations in <tt>Relation</tt>, which are merged.
         #
         # <tt>joins</tt> operations are uniqued so multiple scopes can join in the same table without table aliasing
-        # problems.  If you need to join multiple tables, but still want one of the tables to be uniqued, use the
+        # problems. If you need to join multiple tables, but still want one of the tables to be uniqued, use the
         # array of strings format for your joins.
         #
         #   class Article < ActiveRecord::Base
@@ -1390,7 +1390,7 @@ def sanitize_sql_hash_for_assignment(attrs)
           end.join(', ')
         end
 
-        # Accepts an array of conditions.  The array has each value
+        # Accepts an array of conditions. The array has each value
         # 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)
@@ -1512,7 +1512,7 @@ def initialize(attributes = nil, options = {})
       end
 
       # Populate +coder+ with attributes about this record that should be
-      # serialized.  The structure of +coder+ defined in this method is
+      # serialized. The structure of +coder+ defined in this method is
       # guaranteed to match the structure of +coder+ passed to the +init_with+
       # method.
       #
@@ -1527,8 +1527,8 @@ def encode_with(coder)
         coder['attributes'] = attributes
       end
 
-      # Initialize an empty model object from +coder+.  +coder+ must contain
-      # the attributes necessary for initializing an empty model object.  For
+      # Initialize an empty model object from +coder+. +coder+ must contain
+      # the attributes necessary for initializing an empty model object. For
       # example:
       #
       #   class Post < ActiveRecord::Base

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -104,7 +104,7 @@ def [](name)
       # Available options are (none of these exists by default):
       # * <tt>:limit</tt> -
       #   Requests a maximum column length. This is number of characters for <tt>:string</tt> and
-      #   <tt>:text</tt> columns and number of bytes for :binary and :integer columns.
+      #   <tt>:text</tt> columns and number of bytes for <tt>:binary</tt> and <tt>:integer</tt> columns.
       # * <tt>:default</tt> -
       #   The column's default value. Use nil for NULL.
       # * <tt>:null</tt> -
@@ -153,7 +153,7 @@ def [](name)
       # This method returns <tt>self</tt>.
       #
       # == Examples
-      #  # Assuming td is an instance of TableDefinition
+      #  # Assuming +td+ is an instance of TableDefinition
       #  td.column(:granted, :boolean)
       #  # granted BOOLEAN
       #
@@ -204,7 +204,7 @@ def [](name)
       #   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
@@ -351,7 +351,7 @@ def index_exists?(column_name, options = {})
         @base.index_exists?(@table_name, column_name, options)
       end
 
-      # Adds timestamps (created_at and updated_at) columns to the table. See SchemaStatements#add_timestamps
+      # Adds timestamps (+created_at+ and +updated_at+) columns to the table. See SchemaStatements#add_timestamps
       # ===== Example
       #  t.timestamps
       def timestamps
@@ -398,7 +398,7 @@ def remove_index(options = {})
         @base.remove_index(@table_name, options)
       end
 
-      # Removes the timestamp columns (created_at and updated_at) from the table.
+      # Removes the timestamp columns (+created_at+ and +updated_at+) from the table.
       # ===== Example
       #  t.remove_timestamps
       def remove_timestamps
@@ -412,7 +412,7 @@ def rename(column_name, new_column_name)
         @base.rename_column(@table_name, column_name, new_column_name)
       end
 
-      # Adds a reference. Optionally adds a +type+ column.
+      # Adds a reference. Optionally adds a +type+ column, if <tt>:polymorphic</tt> option is provided.
       # <tt>references</tt> and <tt>belongs_to</tt> are acceptable.
       # ===== Examples
       #  t.references(:goat)

diff --git a/activerecord/lib/active_record/connection_adapters/abstract_adapter.rb b/activerecord/lib/active_record/connection_adapters/abstract_adapter.rb
@@ -46,34 +46,34 @@ def initialize(connection, logger = nil) #:nodoc:
         @instrumenter = ActiveSupport::Notifications.instrumenter
       end
 
-      # Returns the human-readable name of the adapter.  Use mixed case - one
+      # Returns the human-readable name of the adapter. Use mixed case - one
       # can always use downcase if needed.
       def adapter_name
         'Abstract'
       end
 
-      # Does this adapter support migrations?  Backend specific, as the
+      # Does this adapter support migrations? Backend specific, as the
       # abstract adapter always returns +false+.
       def supports_migrations?
         false
       end
 
       # Can this adapter determine the primary key for tables not attached
-      # to an Active Record class, such as join tables?  Backend specific, as
+      # to an Active Record class, such as join tables? Backend specific, as
       # the abstract adapter always returns +false+.
       def supports_primary_key?
         false
       end
 
-      # Does this adapter support using DISTINCT within COUNT?  This is +true+
+      # Does this adapter support using DISTINCT within COUNT? This is +true+
       # for all adapters except sqlite.
       def supports_count_distinct?
         true
       end
 
-      # Does this adapter support DDL rollbacks in transactions?  That is, would
-      # CREATE TABLE or ALTER TABLE get rolled back by a transaction?  PostgreSQL,
-      # SQL Server, and others support this.  MySQL and others do not.
+      # Does this adapter support DDL rollbacks in transactions? That is, would
+      # CREATE TABLE or ALTER TABLE get rolled back by a transaction? PostgreSQL,
+      # SQL Server, and others support this. MySQL and others do not.
       def supports_ddl_transactions?
         false
       end
@@ -89,7 +89,7 @@ def supports_savepoints?
       end
 
       # Should primary key values be selected from their corresponding
-      # sequence before the insert statement?  If true, next_sequence_value
+      # sequence before the insert statement? If true, next_sequence_value
       # is called before each insert to set the record's primary key.
       # This is false for all adapters but Firebird.
       def prefetch_primary_key?(table_name = nil)
@@ -149,7 +149,7 @@ def reset!
 
       ###
       # Clear any caching the database adapter may be doing, for example
-      # clearing the prepared statement cache.  This is database specific.
+      # clearing the prepared statement cache. This is database specific.
       def clear_cache!
         # this should be overridden by concrete adapters
       end

diff --git a/activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb
@@ -5,6 +5,7 @@
 
 module ActiveRecord
   class Base
+    # Establishes a connection to the database that's used by all Active Record objects.
     def self.mysql2_connection(config)
       config[:username] = 'root' if config[:username].nil?
 
@@ -213,6 +214,8 @@ def requires_reloading?
         false
       end
 
+      # Disconnects from the database if already connected.
+      # Otherwise, this method does nothing.
       def disconnect!
         unless @connection.nil?
           @connection.close
@@ -368,6 +371,8 @@ def structure_dump
         end
       end
 
+      # Drops the database specified on the +name+ attribute
+      # and creates it again using the provided +options+.
       def recreate_database(name, options = {})
         drop_database(name)
         create_database(name, options)
@@ -551,6 +556,7 @@ def add_column_position!(sql, options)
         end
       end
 
+      # SHOW VARIABLES LIKE 'name'.
       def show_variable(name)
         variables = select_all("SHOW VARIABLES LIKE '#{name}'")
         variables.first['Value'] unless variables.empty?

diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
@@ -517,6 +517,8 @@ def structure_dump #:nodoc:
         end.join("")
       end
 
+      # Drops the database specified on the +name+ attribute
+      # and creates it again using the provided +options+.
       def recreate_database(name, options = {}) #:nodoc:
         drop_database(name)
         create_database(name, options)

diff --git a/activeresource/lib/active_resource/http_mock.rb b/activeresource/lib/active_resource/http_mock.rb
@@ -9,8 +9,8 @@ class InvalidRequestError < StandardError; end #:nodoc:
   # 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
+  # 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 = {})
@@ -29,7 +29,7 @@ class InvalidRequestError < StandardError; end #:nodoc:
   #   <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
+  # +path+ and <tt>request_headers</tt>. If no match is found an +InvalidRequestError+ exception
   # will be raised showing you what request it could not find a response for and also what requests and response
   # pairs have been recorded so you can create a new mock for that request.
   #
@@ -80,7 +80,7 @@ def delete_duplicate_responses(request)
 
     class << self
 
-      # Returns an array of all request objects that have been sent to the mock.  You can use this to check
+      # Returns an array of all request objects that have been sent to the mock. You can use this to check
       # if your model actually sent an HTTP request.
       #
       # ==== Example
@@ -105,7 +105,7 @@ def requests
       end
 
       # Returns the list of requests and their mocked responses. Look up a
-      # response for a request using responses.assoc(request).
+      # response for a request using <tt>responses.assoc(request)</tt>.
       def responses
         @@responses ||= []
       end
@@ -299,6 +299,8 @@ def initialize(body, message = 200, headers = {})
       end
     end
 
+    # Returns true if code is 2xx,
+    # false otherwise.
     def success?
       code.in?(200..299)
     end
@@ -311,6 +313,8 @@ def []=(key, value)
       headers[key] = value
     end
 
+    # Returns true if the other is a Response with an equal body, equal message
+    # and equal headers. Otherwise it returns false.
     def ==(other)
       if (other.is_a?(Response))
         other.body == body && other.message == message && other.headers == headers

diff --git a/activeresource/lib/active_resource/observing.rb b/activeresource/lib/active_resource/observing.rb
@@ -5,6 +5,14 @@ module Observing
 
     included do
       %w( create save update destroy ).each do |method|
+        # def create_with_notifications(*args, &block)
+        #   notify_observers(:before_create)
+        #   if result = create_without_notifications(*args, &block)
+        #     notify_observers(:after_create)
+        #   end
+        #   result
+        # end
+        # alias_method_chain(create, :notifications)
         class_eval(<<-EOS, __FILE__, __LINE__ + 1)
           def #{method}_with_notifications(*args, &block)
             notify_observers(:before_#{method})

diff --git a/activeresource/lib/active_resource/validations.rb b/activeresource/lib/active_resource/validations.rb
@@ -8,9 +8,9 @@ class ResourceInvalid < ClientError  #:nodoc:
   # Active Resource validation is reported to and from this object, which is used by Base#save
   # to determine whether the object in a valid state to be saved. See usage example in Validations.
   class Errors < ActiveModel::Errors
-    # Grabs errors from an array of messages (like ActiveRecord::Validations)
+    # Grabs errors from an array of messages (like ActiveRecord::Validations).
     # The second parameter directs the errors cache to be cleared (default)
-    # or not (by passing true)
+    # or not (by passing true).
     def from_array(messages, save_cache = false)
       clear unless save_cache
       humanized_attributes = Hash[@base.attributes.keys.map { |attr_name| [attr_name.humanize, attr_name] }]
@@ -73,7 +73,7 @@ def save_with_validation(options={})
 
       # clear the remote validations so they don't interfere with the local
       # ones. Otherwise we get an endless loop and can never change the
-      # fields so as to make the resource valid
+      # fields so as to make the resource valid.
       @remote_errors = nil
       if perform_validation && valid? || !perform_validation
         save_without_validation
@@ -84,15 +84,15 @@ def save_with_validation(options={})
     rescue ResourceInvalid => error
       # cache the remote errors because every call to <tt>valid?</tt> clears
       # all errors. We must keep a copy to add these back after local
-      # validations
+      # validations.
       @remote_errors = error
       load_remote_errors(@remote_errors, true)
       false
     end
 
 
     # Loads the set of remote errors into the object's Errors based on the
-    # content-type of the error-block received
+    # content-type of the error-block received.
     def load_remote_errors(remote_errors, save_cache = false ) #:nodoc:
       case self.class.format
       when ActiveResource::Formats[:xml]