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

Conflicts:
	guides/source/ruby_on_rails_guides_guidelines.textile

actionmailer/lib/action_mailer/base.rb

@@ -14,15 +14,15 @@ module ActionMailer #:nodoc:
   #
   #   $ rails generate mailer Notifier
   #
-  # The generated model inherits from <tt>ActionMailer::Base</tt>. Emails are defined by creating methods
-  # within the model which are then used to set variables to be used in the mail template, to
-  # change options on the mail, or to add attachments.
+  # The generated model inherits from <tt>ActionMailer::Base</tt>. A mailer model defines methods
+  # used to generate an email message. In these methods, you can setup variables to be used in
+  # the mailer views, options on the mail itself such as the <tt>:from</tt> address, and attachments.
   #
   # Examples:
   #
   #   class Notifier < ActionMailer::Base
   #     default :from => 'no-reply@example.com',
-  #            :return_path => 'system@example.com'
+  #             :return_path => 'system@example.com'
   #
   #     def welcome(recipient)
   #       @account = recipient

actionpack/lib/action_view/renderer/partial_renderer.rb

@@ -32,7 +32,7 @@ module ActionView
   #
   #   <%= render :partial => "account", :object => @buyer %>
   #
-  # would provide the +@buyer+ object to the partial, available under the local variable +account+ and is
+  # would provide the <tt>@buyer</tt> object to the partial, available under the local variable +account+ and is
   # equivalent to:
   #
   #   <%= render :partial => "account", :locals => { :account => @buyer } %>

activerecord/lib/active_record/inheritance.rb

@@ -48,6 +48,20 @@ def base_class
       end
 
       # Set this to true if this is an abstract class (see <tt>abstract_class?</tt>).
+      # If you are using inheritance with ActiveRecord and don't want child classes
+      # to utilize the implied STI table name of the parent class, this will need to be true.
+      # For example, given the following:
+      #
+      #   class SuperClass < ActiveRecord::Base
+      #     self.abstract_class = true
+      #   end
+      #   class Child < SuperClass
+      #     self.table_name = 'the_table_i_really_want'
+      #   end
+      # 
+      #
+      # <tt>self.abstract_class = true</tt> is required to make <tt>Child<.find,.create, or any Arel method></tt> use <tt>the_table_i_really_want</tt> instead of a table called <tt>super_classes</tt>
+      #
       attr_accessor :abstract_class
 
       # Returns whether this class is an abstract class or not.

activerecord/lib/active_record/relation.rb

@@ -256,7 +256,7 @@ def scoping
     #   # Update all books with 'Rails' in their title
     #   Book.update_all "author = 'David'", "title LIKE '%Rails%'"
     #
-    #   # Update all avatars migrated more than a week ago
+    #   # Update all avatars migrated more recently than a week ago
     #   Avatar.update_all ['migrated_at = ?', Time.now.utc], ['migrated_at > ?', 1.week.ago]
     #
     #   # Update all books that match conditions, but limit it to 5 ordered by date

guides/source/api_documentation_guidelines.textile

@@ -6,15 +6,15 @@ endprologue.
 
 h3. RDoc
 
-The Rails API documentation is generated with RDoc 2.5. Please consult the documentation for help with the "markup":http://rdoc.rubyforge.org/RDoc/Markup.html, and take into account also these "additional directives":http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html.
+The Rails API documentation is generated with RDoc. Please consult the documentation for help with the "markup":http://rdoc.rubyforge.org/RDoc/Markup.html, and also take into account these "additional directives":http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html.
 
 h3. Wording
 
 Write simple, declarative sentences. Brevity is a plus: get to the point.
 
 Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
 
-Start comments in upper case, follow regular punctuation rules:
+Start comments in upper case. Follow regular punctuation rules:
 
 <ruby>
 # Declares an attribute reader backed by an internally-named instance variable.
@@ -23,7 +23,7 @@ def attr_internal_reader(*attrs)
 end
 </ruby>
 
-Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the recommended idioms in edge, reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.
+Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.
 
 Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?
 
@@ -41,10 +41,9 @@ h3. Example Code
 
 Choose meaningful examples that depict and cover the basics as well as interesting points or gotchas.
 
-Use two spaces to indent chunks of code--that is two spaces with respect to the left margin; the examples
-themselves should use "Rails coding conventions":contributing_to_ruby_on_rails.html#follow-the-coding-conventions.
+Use two spaces to indent chunks of code--that is, for markup purposes, two spaces with respect to the left margin. The examples themselves should use "Rails coding conventions":contributing_to_ruby_on_rails.html#follow-the-coding-conventions.
 
-Short docs do not need an explicit "Examples" label to introduce snippets, they just follow paragraphs:
+Short docs do not need an explicit "Examples" label to introduce snippets; they just follow paragraphs:
 
 <ruby>
 # Converts a collection of elements into a formatted string by calling
@@ -64,7 +63,7 @@ On the other hand, big chunks of structured documentation may have a separate "E
 #   Person.exists?(['name LIKE ?', "%#{query}%"])
 </ruby>
 
-The result of expressions follow them and are introduced by "# => ", vertically aligned:
+The results of expressions follow them and are introduced by "# => ", vertically aligned:
 
 <ruby>
 # For checking if a fixnum is even or odd.
@@ -98,7 +97,7 @@ On the other hand, regular comments do not use an arrow:
 
 h3. Filenames
 
-As a rule of thumb use filenames relative to the application root:
+As a rule of thumb, use filenames relative to the application root:
 
 <plain>
 config/routes.rb            # YES
@@ -111,12 +110,12 @@ h3. Fonts
 h4. Fixed-width Font
 
 Use fixed-width fonts for:
-* constants, in particular class and module names
-* method names
-* literals like +nil+, +false+, +true+, +self+
-* symbols
-* method parameters
-* file names
+* Constants, in particular class and module names.
+* Method names.
+* Literals like +nil+, +false+, +true+, +self+.
+* Symbols.
+* Method parameters.
+* File names.
 
 <ruby>
 class Array
@@ -146,7 +145,7 @@ The description starts in upper case and ends with a full stop—it's standard E
 
 h3. Dynamically Generated Methods
 
-Methods created with +(module|class)_eval(STRING)+ have a comment by their side with an instance of the generated code. That comment is 2 spaces apart from the template:
+Methods created with +(module|class)_eval(STRING)+ have a comment by their side with an instance of the generated code. That comment is 2 spaces away from the template:
 
 <ruby>
 for severity in Severity.constants
@@ -162,7 +161,7 @@ for severity in Severity.constants
 end
 </ruby>
 
-If the resulting lines are too wide, say 200 columns or more, we put the comment above the call:
+If the resulting lines are too wide, say 200 columns or more, put the comment above the call:
 
 <ruby>
 # def self.find_by_login_and_activated(*args)

guides/source/asset_pipeline.textile

@@ -409,7 +409,9 @@ cannot see application objects or methods. *Heroku requires this to be false.*
 WARNING: If you set +config.assets.initialize_on_precompile+ to false, be sure to
 test +rake assets:precompile+ locally before deploying. It may expose bugs where
 your assets reference application objects or methods, since those are still
-in scope in development mode regardless of the value of this flag.
+in scope in development mode regardless of the value of this flag. Changing this flag also effects
+engines. Engines can define assets for precompilation as well. Since the complete environment is not loaded,
+engines (or other gems) will not be loaded which can cause missing assets.
 
 Capistrano (v2.8.0 and above) includes a recipe to handle this in deployment. Add the following line to +Capfile+:
 

guides/source/association_basics.textile

@@ -342,9 +342,9 @@ In designing a data model, you will sometimes find a model that should have a re
 
 <ruby>
 class Employee < ActiveRecord::Base
-  has_many :subordinates, :class_name => "Employee"
-  belongs_to :manager, :class_name => "Employee",
+  has_many :subordinates, :class_name => "Employee",
     :foreign_key => "manager_id"
+  belongs_to :manager, :class_name => "Employee"
 end
 </ruby>
 

guides/source/caching_with_rails.textile

@@ -257,7 +257,9 @@ However, it's important to note that query caches are created at the start of an
 
 h3. Cache Stores
 
-Rails provides different stores for the cached data created by action and fragment caches. Page caches are always stored on disk.
+Rails provides different stores for the cached data created by <b>action</b> and <b>fragment</b> caches.
+
+TIP: Page caches are always stored on disk.
 
 h4. Configuration
 
@@ -267,7 +269,7 @@ You can set up your application's default cache store by calling +config.cache_s
 config.cache_store = :memory_store
 </ruby>
 
-Alternatively, you can call +ActionController::Base.cache_store+ outside of a configuration block.
+NOTE: Alternatively, you can call +ActionController::Base.cache_store+ outside of a configuration block.
 
 You can access the cache by calling +Rails.cache+.
 
@@ -294,7 +296,7 @@ h4. ActiveSupport::Cache::MemoryStore
 This cache store keeps entries in memory in the same Ruby process. The cache store has a bounded size specified by the +:size+ options to the initializer (default is 32Mb). When the cache exceeds the allotted size, a cleanup will occur and the least recently used entries will be removed.
 
 <ruby>
-ActionController::Base.cache_store = :memory_store, :size => 64.megabytes
+config.cache_store = :memory_store, :size => 64.megabytes
 </ruby>
 
 If you're running multiple Ruby on Rails server processes (which is the case if you're using mongrel_cluster or Phusion Passenger), then your Rails server process instances won't be able to share cache data with each other. This cache store is not appropriate for large application deployments, but can work well for small, low traffic sites with only a couple of server processes or for development and test environments.
@@ -306,7 +308,7 @@ h4. ActiveSupport::Cache::FileStore
 This cache store uses the file system to store entries. The path to the directory where the store files will be stored must be specified when initializing the cache.
 
 <ruby>
-ActionController::Base.cache_store = :file_store, "/path/to/cache/directory"
+config.cache_store = :file_store, "/path/to/cache/directory"
 </ruby>
 
 With this cache store, multiple server processes on the same host can share a cache. Servers processes running on different hosts could share a cache by using a shared file system, but that set up would not be ideal and is not recommended. The cache store is appropriate for low to medium traffic sites that are served off one or two hosts.
@@ -322,15 +324,15 @@ When initializing the cache, you need to specify the addresses for all memcached
 The +write+ and +fetch+ methods on this cache accept two additional options that take advantage of features specific to memcached. You can specify +:raw+ to send a value directly to the server with no serialization. The value must be a string or number. You can use memcached direct operation like +increment+ and +decrement+ only on raw values. You can also specify +:unless_exist+ if you don't want memcached to overwrite an existing entry.
 
 <ruby>
-ActionController::Base.cache_store = :mem_cache_store, "cache-1.example.com", "cache-2.example.com"
+config.cache_store = :mem_cache_store, "cache-1.example.com", "cache-2.example.com"
 </ruby>
 
 h4. ActiveSupport::Cache::EhcacheStore
 
 If you are using JRuby you can use Terracotta's Ehcache as the cache store for your application. Ehcache is an open source Java cache that also offers an enterprise version with increased scalability, management, and commercial support. You must first install the jruby-ehcache-rails3 gem (version 1.1.0 or later) to use this cache store.
 
 <ruby>
-ActionController::Base.cache_store = :ehcache_store
+config.cache_store = :ehcache_store
 </ruby>
 
 When initializing the cache, you may use the +:ehcache_config+ option to specify the Ehcache config file to use (where the default is "ehcache.xml" in your Rails config directory), and the :cache_name option to provide a custom name for your cache (the default is rails_cache).
@@ -359,7 +361,7 @@ h4. ActiveSupport::Cache::NullStore
 This cache store implementation is meant to be used only in development or test environments and it never stores anything. This can be very useful in development when you have code that interacts directly with +Rails.cache+, but caching may interfere with being able to see the results of code changes. With this cache store, all +fetch+ and +read+ operations will result in a miss.
 
 <ruby>
-ActionController::Base.cache_store = :null_store
+config.cache_store = :null_store
 </ruby>
 
 h4. Custom Cache Stores
@@ -369,7 +371,7 @@ You can create your own custom cache store by simply extending +ActiveSupport::C
 To use a custom cache store, simple set the cache store to a new instance of the class.
 
 <ruby>
-ActionController::Base.cache_store = MyCacheStore.new
+config.cache_store = MyCacheStore.new
 </ruby>
 
 h4. Cache Keys