diff options
17 files changed, 85 insertions, 46 deletions
diff --git a/actionpack/README.rdoc b/actionpack/README.rdoc index 0e7d164623..b297ceb0e2 100644 --- a/actionpack/README.rdoc +++ b/actionpack/README.rdoc @@ -1,6 +1,6 @@ = Action Pack -- From request to response -Action Pack is a framework for handling and responding to web requests. It it +Action Pack is a framework for handling and responding to web requests. It provides mechanisms for *routing* (mapping request URLs to actions), defining *controllers* that implement actions, and generating responses by rendering *views*, which are templates of various formats. In short, Action Pack diff --git a/activemodel/lib/active_model/errors.rb b/activemodel/lib/active_model/errors.rb index 05e353ce18..272ddb1554 100644 --- a/activemodel/lib/active_model/errors.rb +++ b/activemodel/lib/active_model/errors.rb @@ -37,11 +37,11 @@ module ActiveModel # send(attr) # end # - # def ErrorsPerson.human_attribute_name(attr, options = {}) + # def Person.human_attribute_name(attr, options = {}) # attr # end # - # def ErrorsPerson.lookup_ancestors + # def Person.lookup_ancestors # [self] # end # diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb index 5670ec74cb..e675937f4d 100644 --- a/activemodel/lib/active_model/serialization.rb +++ b/activemodel/lib/active_model/serialization.rb @@ -61,6 +61,8 @@ module ActiveModel # person.serializable_hash # => {"name"=>"Bob"} # person.to_json # => "{\"name\":\"Bob\"}" # person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person... + # + # Valid options are <tt>:only</tt>, <tt>:except</tt> and <tt>:methods</tt> . module Serialization def serializable_hash(options = nil) options ||= {} diff --git a/activerecord/lib/active_record/associations/has_many_association.rb b/activerecord/lib/active_record/associations/has_many_association.rb index d74fb7c702..c33bc6aa47 100644 --- a/activerecord/lib/active_record/associations/has_many_association.rb +++ b/activerecord/lib/active_record/associations/has_many_association.rb @@ -24,7 +24,7 @@ module ActiveRecord # If the association has a counter cache it gets that value. Otherwise # it will attempt to do a count via SQL, bounded to <tt>:limit</tt> if # there's one. Some configuration options like :group make it impossible - # to do a SQL count, in those cases the array count will be used. + # to do an SQL count, in those cases the array count will be used. # # That does not depend on whether the collection has already been loaded # or not. The +size+ method is the one that takes the loaded flag into diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 7710aa7c54..8da4fbcba7 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -516,7 +516,8 @@ module ActiveRecord #:nodoc: connection.select_value(sql, "#{name} Count").to_i end - # Attributes listed as readonly can be set for a new record, but will be ignored in database updates afterwards. + # Attributes listed as readonly will be used to create a new record but update operations will + # ignore these fields. def attr_readonly(*attributes) write_inheritable_attribute(:attr_readonly, Set.new(attributes.map(&:to_s)) + (readonly_attributes || [])) end @@ -604,8 +605,8 @@ module ActiveRecord #:nodoc: (parents.detect{ |p| p.respond_to?(:table_name_prefix) } || self).table_name_prefix end - # Defines the column name for use with single table inheritance - # -- can be set in subclasses like so: self.inheritance_column = "type_id" + # Defines the column name for use with single table inheritance. Use + # <tt>set_inheritance_column</tt> to set a different value. def inheritance_column @inheritance_column ||= "type".freeze end @@ -622,8 +623,8 @@ module ActiveRecord #:nodoc: default end - # 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. + # 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 # set_table_name "project" @@ -1034,8 +1035,8 @@ module ActiveRecord #:nodoc: end protected - # Scope parameters to method calls within the block. Takes a hash of method_name => parameters hash. - # method_name may be <tt>:find</tt> or <tt>:create</tt>. <tt>:find</tt> parameter is <tt>Relation</tt> while + # with_scope lets you apply options to inner block incrementally. It takes a hash and the keys must be + # <tt>:find</tt> or <tt>:create</tt>. <tt>:find</tt> parameter is <tt>Relation</tt> while # <tt>:create</tt> parameters are an attributes hash. # # class Article < ActiveRecord::Base @@ -1080,8 +1081,7 @@ module ActiveRecord #:nodoc: # end # end # - # *Note*: the +:find+ scope also has effect on update and deletion methods, - # like +update_all+ and +delete_all+. + # *Note*: the +:find+ scope also has effect on update and deletion methods, like +update_all+ and +delete_all+. def with_scope(method_scoping = {}, action = :merge, &block) method_scoping = method_scoping.method_scoping if method_scoping.respond_to?(:method_scoping) diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb index 7f10fbf8b0..aa92bf999f 100644 --- a/activerecord/lib/active_record/callbacks.rb +++ b/activerecord/lib/active_record/callbacks.rb @@ -68,8 +68,8 @@ module ActiveRecord # end # # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is - # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the situation where - # we've implemented the save behavior through overwriteable methods: + # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the following situation + # where the +before_destroy+ methis is overriden: # # class Topic < ActiveRecord::Base # def before_destroy() destroy_author end diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb index 4118ea7b31..a130c330dd 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb @@ -42,7 +42,7 @@ module ActiveRecord 65535 end - # the maximum length of a SQL query + # the maximum length of an SQL query def sql_query_length 1048575 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 9fc0e6d403..9118ceb33c 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb @@ -537,7 +537,7 @@ module ActiveRecord end end - # Represents a SQL table in an abstract way for updating a table. + # Represents an SQL table in an abstract way for updating a table. # Also see TableDefinition and SchemaStatements#create_table # # Available transformations are: diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb index cc7c07dc35..ba0051de05 100644 --- a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb @@ -278,7 +278,7 @@ module ActiveRecord rows end - # Executes a SQL query and returns a MySQL::Result object. Note that you have to free + # Executes an SQL query and returns a MySQL::Result object. Note that you have to free # the Result object after you're done using it. def execute(sql, name = nil) #:nodoc: if name == :skip_logging diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb index 8f44f03d56..71b46beaef 100644 --- a/activerecord/lib/active_record/persistence.rb +++ b/activerecord/lib/active_record/persistence.rb @@ -60,7 +60,7 @@ module ActiveRecord # reflect that no changes should be made (since they can't be # persisted). Returns the frozen instance. # - # The row is simply removed with a SQL +DELETE+ statement on the + # The row is simply removed with an SQL +DELETE+ statement on the # record's primary key, and no callbacks are executed. # # To enforce the object's +before_destroy+ and +after_destroy+ diff --git a/activerecord/lib/active_record/railties/databases.rake b/activerecord/lib/active_record/railties/databases.rake index 2c17c74ab4..ae605d3e7a 100644 --- a/activerecord/lib/active_record/railties/databases.rake +++ b/activerecord/lib/active_record/railties/databases.rake @@ -339,7 +339,7 @@ namespace :db do end namespace :structure do - desc "Dump the database structure to a SQL file" + desc "Dump the database structure to an SQL file" task :dump => :environment do abcs = ActiveRecord::Base.configurations case abcs[Rails.env]["adapter"] diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb index 0fafd56f33..50a4ce695e 100644 --- a/activesupport/lib/active_support/callbacks.rb +++ b/activesupport/lib/active_support/callbacks.rb @@ -571,7 +571,9 @@ module ActiveSupport # # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling # <tt>"#{kind}_#{name}"</tt> on the given instance. In this case "kind" is "before" and - # "name" is "save". + # "name" is "save". In this context treat ":kind" and ":name" as special thing where + # ":kind" refers to "callback type(before/after)" and ":name" refers to the method on + # which callbacks are being defined. # # A declaration like # diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb index eb31f7cad4..408d327dd7 100644 --- a/activesupport/lib/active_support/concern.rb +++ b/activesupport/lib/active_support/concern.rb @@ -1,3 +1,38 @@ +# A typical module looks like this +# +# module M +# def self.included(base) +# base.send(:extend, ClassMethods) +# base.send(:include, InstanceMethods) +# scope :foo, :conditions => {:created_at => nil} +# end +# +# module ClassMethods +# def cm; puts 'I am class method'; end +# end +# +# module InstanceMethods +# def im; puts 'I am instance method'; end +# end +# end +# +# By using <tt>ActiveSupport::Concern</tt> above module could be written as: +# +# module M +# extend ActiveSupport::Concern +# +# included do +# scope :foo, :conditions => {:created_at => nil} +# end +# +# module ClassMethods +# def cm; puts 'I am class method'; end +# end +# +# module InstanceMethods +# def im; puts 'I am instance method'; end +# end +# end module ActiveSupport module Concern def self.extended(base) diff --git a/railties/guides/source/api_documentation_guidelines.textile b/railties/guides/source/api_documentation_guidelines.textile index d9a0d39d9d..9f201de49b 100644 --- a/railties/guides/source/api_documentation_guidelines.textile +++ b/railties/guides/source/api_documentation_guidelines.textile @@ -29,7 +29,7 @@ Documentation has to be concise but comprehensive. Explore and document edge cas The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. Historically there has been lack of consistency regarding this, but we checked with David when docrails started. All Rails documentation consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be fenomenal :). -Spell names correctly: HTML, MySQL, JavaScript, ERb. +Spell names correctly: HTML, MySQL, JavaScript, ERb. Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database". h3. Example Code diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 12f2bb146b..ffb0310816 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -213,9 +213,9 @@ If you open this file in a new Rails application, you'll see a default database * The +test+ environment is used to run automated tests * The +production+ environment is used when you deploy your application for the world to use. -h5. Configuring a SQLite3 Database +h5. Configuring an SQLite3 Database -Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using a SQLite database when creating a new project, but you can always change it later. +Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using an SQLite database when creating a new project, but you can always change it later. Here's the section of the default configuration file (<tt>config/database.yml</tt>) with connection information for the development environment: diff --git a/railties/lib/rails/generators/rails/app/templates/config/databases/oracle.yml b/railties/lib/rails/generators/rails/app/templates/config/databases/oracle.yml index f99ee937f3..fddf8b8144 100644 --- a/railties/lib/rails/generators/rails/app/templates/config/databases/oracle.yml +++ b/railties/lib/rails/generators/rails/app/templates/config/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 an SQL connect string of the form: # # //host:[port][/service name] # diff --git a/railties/lib/rails/railtie.rb b/railties/lib/rails/railtie.rb index f0d9d95fc4..8a6e2716dc 100644 --- a/railties/lib/rails/railtie.rb +++ b/railties/lib/rails/railtie.rb @@ -6,53 +6,53 @@ require 'active_support/deprecation' module Rails # Railtie is the core of the Rails Framework and provides several hooks to extend # Rails and/or modify the initialization process. - # + # # Every major component of Rails (Action Mailer, Action Controller, # Action View, Active Record and Active Resource) are all Railties, so each of # them is responsible to set their own initialization. This makes, for example, # Rails absent of any Active Record hook, allowing any other ORM framework to hook in. - # + # # Developing a Rails extension does _not_ require any implementation of # Railtie, but if you need to interact with the Rails framework during # or after boot, then Railtie is what you need to do that interaction. - # + # # For example, the following would need you to implement Railtie in your # plugin: - # + # # * creating initializers # * configuring a Rails framework or the Application, like setting a generator # * adding Rails config.* keys to the environment # * setting up a subscriber to the Rails +ActiveSupport::Notifications+ # * adding rake tasks into rails - # + # # == Creating your Railtie # # Implementing Railtie in your Rails extension is done by creating a class # Railtie that has your extension name and making sure that this gets loaded # during boot time of the Rails stack. - # + # # You can do this however you wish, but here is an example if you want to provide # it for a gem that can be used with or without Rails: - # + # # * Create a file (say, lib/my_gem/railtie.rb) which contains class Railtie inheriting from # Rails::Railtie and is namespaced to your gem: # - # # lib/my_gem/railtie.rb - # module MyGem - # class Railtie < Rails::Railtie + # # lib/my_gem/railtie.rb + # module MyGem + # class Railtie < Rails::Railtie + # end # end - # end - # + # # * Require your own gem as well as rails in this file: - # - # # lib/my_gem/railtie.rb - # require 'my_gem' - # require 'rails' - # - # module MyGem - # class Railtie < Rails::Railtie + # + # # lib/my_gem/railtie.rb + # require 'my_gem' + # require 'rails' + # + # module MyGem + # class Railtie < Rails::Railtie + # end # end - # end # # == Initializers # @@ -65,7 +65,7 @@ module Rails # end # end # - # If specified, the block can also receive the application object, in case you + # If specified, the block can also receive the application object, in case you # need to access some application specific configuration, like middleware: # # class MyRailtie < Rails::Railtie |