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

Conflicts:
	guides/source/migrations.md

actionmailer/lib/action_mailer/base.rb

@@ -20,8 +20,6 @@ module ActionMailer
   # 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'

actionpack/lib/abstract_controller/helpers.rb

@@ -58,11 +58,10 @@ def #{meth}(*args, &blk)                               # def current_user(*args,
 
       # The +helper+ class method can take a series of helper module names, a block, or both.
       #
-      # ==== Parameters
+      # ==== Options
       # * <tt>*args</tt> - Module, Symbol, String, :all
       # * <tt>block</tt> - A block defining helper methods
       #
-      # ==== Examples
       # When the argument is a module it will be included directly in the template class.
       #   helper FooHelper # => includes FooHelper
       #

actionpack/lib/action_controller/caching.rb

@@ -6,8 +6,7 @@ module ActionController
   # \Caching is a cheap way of speeding up slow applications by keeping the result of
   # calculations, renderings, and database calls around for subsequent requests.
   #
-  # You can read more about each approach and the by clicking the
-  # modules below.
+  # You can read more about each approach by clicking the modules below.
   #
   # Note: To turn off all caching, set
   #   config.action_controller.perform_caching = false.

actionpack/lib/action_controller/metal/streaming.rb

@@ -21,8 +21,6 @@ module ActionController #:nodoc:
   # supports fibers (fibers are supported since version 1.9.2 of the main
   # Ruby implementation).
   #
-  # == Examples
-  #
   # Streaming can be added to a given template easily, all you need to do is
   # to pass the :stream option.
   #

actionpack/lib/action_dispatch/middleware/flash.rb

@@ -105,7 +105,7 @@ def initialize_copy(other)
         super
       end
 
-      def []=(k, v) #:nodoc:
+      def []=(k, v)
         @discard.delete k
         @flashes[k] = v
       end

actionpack/lib/action_dispatch/railtie.rb

 require "action_dispatch"
 
 module ActionDispatch
-  class Railtie < Rails::Railtie
+  class Railtie < Rails::Railtie # :nodoc:
     config.action_dispatch = ActiveSupport::OrderedOptions.new
     config.action_dispatch.x_sendfile_header = nil
     config.action_dispatch.ip_spoofing_check = true

actionpack/lib/action_dispatch/routing.rb

@@ -191,8 +191,6 @@ module ActionDispatch
   # <tt>:any</tt> which means that the route will respond to any of the HTTP
   # methods.
   #
-  # Examples:
-  #
   #   match 'post/:id' => 'posts#show', via: :get
   #   match 'post/:id' => 'posts#create_comment', via: :post
   #
@@ -204,8 +202,6 @@ module ActionDispatch
   # An alternative method of specifying which HTTP method a route should respond to is to use the helper
   # methods <tt>get</tt>, <tt>post</tt>, <tt>patch</tt>, <tt>put</tt> and <tt>delete</tt>.
   #
-  # Examples:
-  #
   #   get 'post/:id' => 'posts#show'
   #   post 'post/:id' => 'posts#create_comment'
   #

actionpack/lib/action_dispatch/routing/mapper.rb

@@ -624,8 +624,6 @@ module Scoping
         #
         # Takes same options as <tt>Base#match</tt> and <tt>Resources#resources</tt>.
         #
-        # === Examples
-        #
         #   # route /posts (without the prefix /admin) to <tt>Admin::PostsController</tt>
         #   scope module: "admin" do
         #     resources :posts
@@ -706,8 +704,6 @@ def controller(controller, options={})
         # For options, see <tt>Base#match</tt>. For +:shallow_path+ option, see
         # <tt>Resources#resources</tt>.
         #
-        # === Examples
-        #
         #   # accessible through /sekret/posts rather than /admin/posts
         #   namespace :admin, path: "sekret" do
         #     resources :posts

actionpack/lib/action_dispatch/routing/polymorphic_routes.rb

@@ -74,8 +74,6 @@ module PolymorphicRoutes
       # * <tt>:routing_type</tt> - Allowed values are <tt>:path</tt> or <tt>:url</tt>.
       #   Default is <tt>:url</tt>.
       #
-      # ==== Examples
-      #
       #   # an Article record
       #   polymorphic_url(record)  # same as article_url(record)
       #

actionpack/lib/action_dispatch/testing/assertions/selector.rb

@@ -155,8 +155,6 @@ def css_select(*args)
       # If the method is called with a block, once all equality tests are
       # evaluated the block is called with an array of all matched elements.
       #
-      # ==== Examples
-      #
       #   # At least one form element
       #   assert_select "form"
       #

actionpack/lib/action_view/helpers/asset_tag_helper.rb

@@ -32,6 +32,9 @@ module AssetTagHelper
       # You can modify the HTML attributes of the script tag by passing a hash as the
       # last argument.
       #
+      # When the Asset Pipeline is enabled, you can pass the name of your manifest as
+      # source, and include other JavaScript or CoffeeScript files inside the manifest.
+      #
       #   javascript_include_tag "xmlhr"
       #   # => <script src="/assets/xmlhr.js?1284139606"></script>
       #
@@ -106,19 +109,18 @@ def stylesheet_link_tag(*sources)
       # * <tt>:type</tt>  - Override the auto-generated mime type
       # * <tt>:title</tt>  - Specify the title of the link, defaults to the +type+
       #
-      # ==== Examples
-      #  auto_discovery_link_tag
-      #  # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/action" />
-      #  auto_discovery_link_tag(:atom)
-      #  # => <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.currenthost.com/controller/action" />
-      #  auto_discovery_link_tag(:rss, {action: "feed"})
-      #  # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/feed" />
-      #  auto_discovery_link_tag(:rss, {action: "feed"}, {title: "My RSS"})
-      #  # => <link rel="alternate" type="application/rss+xml" title="My RSS" href="http://www.currenthost.com/controller/feed" />
-      #  auto_discovery_link_tag(:rss, {controller: "news", action: "feed"})
-      #  # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/news/feed" />
-      #  auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {title: "Example RSS"})
-      #  # => <link rel="alternate" type="application/rss+xml" title="Example RSS" href="http://www.example.com/feed" />
+      #   auto_discovery_link_tag
+      #   # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/action" />
+      #   auto_discovery_link_tag(:atom)
+      #   # => <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.currenthost.com/controller/action" />
+      #   auto_discovery_link_tag(:rss, {action: "feed"})
+      #   # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/feed" />
+      #   auto_discovery_link_tag(:rss, {action: "feed"}, {title: "My RSS"})
+      #   # => <link rel="alternate" type="application/rss+xml" title="My RSS" href="http://www.currenthost.com/controller/feed" />
+      #   auto_discovery_link_tag(:rss, {controller: "news", action: "feed"})
+      #   # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/news/feed" />
+      #   auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {title: "Example RSS"})
+      #   # => <link rel="alternate" type="application/rss+xml" title="Example RSS" href="http://www.example.com/feed" />
       def auto_discovery_link_tag(type = :rss, url_options = {}, tag_options = {})
         if !(type == :rss || type == :atom) && tag_options[:type].blank?
           message = "You have passed type other than :rss or :atom to auto_discovery_link_tag and haven't supplied " +
@@ -137,27 +139,24 @@ def auto_discovery_link_tag(type = :rss, url_options = {}, tag_options = {})
         )
       end
 
-      #   <%= favicon_link_tag %>
-      #
-      # generates
-      #
-      #   <link href="/assets/favicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon" />
-      #
-      # You may specify a different file in the first argument:
+      # Returns a link loading a favicon file. You may specify a different file
+      # in the first argument. The helper accepts an additional options hash where
+      # you can override "rel" and "type".
       #
-      #   <%= favicon_link_tag '/myicon.ico' %>
-      #
-      # That's passed to +path_to_image+ as is, so it gives
-      #
-      #   <link href="/myicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon" />
+      # ==== Options
+      # * <tt>:rel</tt>   - Specify the relation of this link, defaults to 'shortcut icon'
+      # * <tt>:type</tt>  - Override the auto-generated mime type, defaults to 'image/vnd.microsoft.icon'
       #
-      # The helper accepts an additional options hash where you can override "rel" and "type".
+      #   favicon_link_tag '/myicon.ico'
+      #   # => <link href="/assets/favicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon" />
       #
-      # For example, Mobile Safari looks for a different LINK tag, pointing to an image that
+      # Mobile Safari looks for a different <link> tag, pointing to an image that
       # will be used if you add the page to the home screen of an iPod Touch, iPhone, or iPad.
       # The following call would generate such a tag:
       #
-      #   <%= favicon_link_tag 'mb-icon.png', rel: 'apple-touch-icon', type: 'image/png' %>
+      #   favicon_link_tag '/mb-icon.png', rel: 'apple-touch-icon', type: 'image/png'
+      #   # => <link href="/assets/mb-icon.png" rel="apple-touch-icon" type="image/png" />
+      #
       def favicon_link_tag(source='favicon.ico', options={})
         tag('link', {
           :rel  => 'shortcut icon',
@@ -166,7 +165,7 @@ def favicon_link_tag(source='favicon.ico', options={})
         }.merge(options.symbolize_keys))
       end
 
-      # Returns an html image tag for the +source+. The +source+ can be a full
+      # Returns an HTML image tag for the +source+. The +source+ can be a full
       # path or a file.
       #
       # ==== Options
@@ -179,18 +178,18 @@ def favicon_link_tag(source='favicon.ico', options={})
       #   width="30" and height="45", and "50" becomes width="50" and height="50".
       #   <tt>:size</tt> will be ignored if the value is not in the correct format.
       #
-      #  image_tag("icon")
-      #  # => <img alt="Icon" src="/assets/icon" />
-      #  image_tag("icon.png")
-      #  # => <img alt="Icon" src="/assets/icon.png" />
-      #  image_tag("icon.png", size: "16x10", alt: "Edit Entry")
-      #  # => <img src="/assets/icon.png" width="16" height="10" alt="Edit Entry" />
-      #  image_tag("/icons/icon.gif", size: "16")
-      #  # => <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
-      #  image_tag("/icons/icon.gif", height: '32', width: '32')
-      #  # => <img alt="Icon" height="32" src="/icons/icon.gif" width="32" />
-      #  image_tag("/icons/icon.gif", class: "menu_icon")
-      #  # => <img alt="Icon" class="menu_icon" src="/icons/icon.gif" />
+      #   image_tag("icon")
+      #   # => <img alt="Icon" src="/assets/icon" />
+      #   image_tag("icon.png")
+      #   # => <img alt="Icon" src="/assets/icon.png" />
+      #   image_tag("icon.png", size: "16x10", alt: "Edit Entry")
+      #   # => <img src="/assets/icon.png" width="16" height="10" alt="Edit Entry" />
+      #   image_tag("/icons/icon.gif", size: "16")
+      #   # => <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
+      #   image_tag("/icons/icon.gif", height: '32', width: '32')
+      #   # => <img alt="Icon" height="32" src="/icons/icon.gif" width="32" />
+      #   image_tag("/icons/icon.gif", class: "menu_icon")
+      #   # => <img alt="Icon" class="menu_icon" src="/icons/icon.gif" />
       def image_tag(source, options={})
         options = options.symbolize_keys
 
@@ -208,6 +207,9 @@ def image_tag(source, options={})
         tag("img", options)
       end
 
+      # Returns a string suitable for an html image tag alt attribute.
+      # +src+ is meant to be an image file path.
+      # It removes the basename of the file path and the digest, if any.
       def image_alt(src)
         File.basename(src, '.*').sub(/-[[:xdigit:]]{32}\z/, '').capitalize
       end
@@ -228,24 +230,24 @@ def image_alt(src)
       #   width="30" and height="45". <tt>:size</tt> will be ignored if the
       #   value is not in the correct format.
       #
-      #  video_tag("trailer")
-      #  # => <video src="/videos/trailer" />
-      #  video_tag("trailer.ogg")
-      #  # => <video src="/videos/trailer.ogg" />
-      #  video_tag("trailer.ogg", controls: true, autobuffer: true)
-      #  # => <video autobuffer="autobuffer" controls="controls" src="/videos/trailer.ogg" />
-      #  video_tag("trailer.m4v", size: "16x10", poster: "screenshot.png")
-      #  # => <video src="/videos/trailer.m4v" width="16" height="10" poster="/assets/screenshot.png" />
-      #  video_tag("/trailers/hd.avi", size: "16x16")
-      #  # => <video src="/trailers/hd.avi" width="16" height="16" />
-      #  video_tag("/trailers/hd.avi", height: '32', width: '32')
-      #  # => <video height="32" src="/trailers/hd.avi" width="32" />
-      #  video_tag("trailer.ogg", "trailer.flv")
-      #  # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
-      #  video_tag(["trailer.ogg", "trailer.flv"])
-      #  # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
-      #  video_tag(["trailer.ogg", "trailer.flv"], size: "160x120")
-      #  # => <video height="120" width="160"><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
+      #   video_tag("trailer")
+      #   # => <video src="/videos/trailer" />
+      #   video_tag("trailer.ogg")
+      #   # => <video src="/videos/trailer.ogg" />
+      #   video_tag("trailer.ogg", controls: true, autobuffer: true)
+      #   # => <video autobuffer="autobuffer" controls="controls" src="/videos/trailer.ogg" />
+      #   video_tag("trailer.m4v", size: "16x10", poster: "screenshot.png")
+      #   # => <video src="/videos/trailer.m4v" width="16" height="10" poster="/assets/screenshot.png" />
+      #   video_tag("/trailers/hd.avi", size: "16x16")
+      #   # => <video src="/trailers/hd.avi" width="16" height="16" />
+      #   video_tag("/trailers/hd.avi", height: '32', width: '32')
+      #   # => <video height="32" src="/trailers/hd.avi" width="32" />
+      #   video_tag("trailer.ogg", "trailer.flv")
+      #   # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
+      #   video_tag(["trailer.ogg", "trailer.flv"])
+      #   # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
+      #   video_tag(["trailer.ogg", "trailer.flv"], size: "160x120")
+      #   # => <video height="120" width="160"><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
       def video_tag(*sources)
         multiple_sources_tag('video', sources) do |options|
           options[:poster] = path_to_image(options[:poster]) if options[:poster]
@@ -256,18 +258,18 @@ def video_tag(*sources)
         end
       end
 
-      # Returns an html audio tag for the +source+.
+      # Returns an HTML audio tag for the +source+.
       # The +source+ can be full path or file that exists in
       # your public audios directory.
       #
-      #   audio_tag("sound")  # =>
-      #     <audio src="/audios/sound" />
-      #   audio_tag("sound.wav")  # =>
-      #     <audio src="/audios/sound.wav" />
-      #   audio_tag("sound.wav", autoplay: true, controls: true)  # =>
-      #     <audio autoplay="autoplay" controls="controls" src="/audios/sound.wav" />
-      #   audio_tag("sound.wav", "sound.mid")  # =>
-      #     <audio><source src="/audios/sound.wav" /><source src="/audios/sound.mid" /></audio>
+      #   audio_tag("sound")
+      #   # => <audio src="/audios/sound" />
+      #   audio_tag("sound.wav")
+      #   # => <audio src="/audios/sound.wav" />
+      #   audio_tag("sound.wav", autoplay: true, controls: true)
+      #   # => <audio autoplay="autoplay" controls="controls" src="/audios/sound.wav" />
+      #   audio_tag("sound.wav", "sound.mid")
+      #   # => <audio><source src="/audios/sound.wav" /><source src="/audios/sound.mid" /></audio>
       def audio_tag(*sources)
         multiple_sources_tag('audio', sources)
       end

actionpack/lib/action_view/helpers/asset_url_helper.rb

@@ -2,7 +2,7 @@
 
 module ActionView
   # = Action View Asset URL Helpers
-  module Helpers #:nodoc:
+  module Helpers
     # This module provides methods for generating asset paths and
     # urls.
     #

actionpack/lib/action_view/helpers/atom_feed_helper.rb

@@ -2,7 +2,7 @@
 
 module ActionView
   # = Action View Atom Feed Helpers
-  module Helpers #:nodoc:
+  module Helpers
     module AtomFeedHelper
       # Adds easy defaults to writing Atom feeds with the Builder template engine (this does not work on ERB or any other
       # template languages).
@@ -124,7 +124,7 @@ def atom_feed(options = {}, &block)
         end
       end
 
-      class AtomBuilder
+      class AtomBuilder #:nodoc:
         XHTML_TAG_NAMES = %w(content rights title subtitle summary).to_set
 
         def initialize(xml)
@@ -158,7 +158,7 @@ def xhtml_block?(method, arguments)
           end
       end
 
-      class AtomFeedBuilder < AtomBuilder
+      class AtomFeedBuilder < AtomBuilder #:nodoc:
         def initialize(xml, view, feed_options = {})
           @xml, @view, @feed_options = xml, view, feed_options
         end

actionpack/lib/action_view/helpers/benchmark_helper.rb

@@ -2,7 +2,7 @@
 
 module ActionView
   module Helpers
-    module BenchmarkHelper
+    module BenchmarkHelper #:nodoc:
       include ActiveSupport::Benchmarkable
 
       def benchmark(*)

actionpack/lib/action_view/helpers/capture_helper.rb

@@ -42,14 +42,12 @@ def capture(*args)
       end
 
       # Calling content_for stores a block of markup in an identifier for later use.
-      # You can make subsequent calls to the stored content in other templates, helper modules
-      # or the layout by passing the identifier as an argument to <tt>content_for</tt>.
+      # In order to access this stored content in other templates, helper modules
+      # or the layout, you would pass the identifier as an argument to <tt>content_for</tt>.
       #
       # Note: <tt>yield</tt> can still be used to retrieve the stored content, but calling
       # <tt>yield</tt> doesn't work in helper modules, while <tt>content_for</tt> does.
       #
-      # ==== Examples
-      #
       #   <% content_for :not_authorized do %>
       #     alert('You are not authorized to do that!')
       #   <% end %>
@@ -74,7 +72,8 @@ def capture(*args)
       #
       #   <%= stored_content %>
       #
-      # You can use the <tt>yield</tt> syntax alongside an existing call to <tt>yield</tt> in a layout. For example:
+      # You can also use the <tt>yield</tt> syntax alongside an existing call to
+      # <tt>yield</tt> in a layout. For example:
       #
       #   <%# This is the layout %>
       #   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -115,7 +114,7 @@ def capture(*args)
       #     <li><%= link_to 'Home', action: 'index' %></li>
       #   <% end %>
       #
-      #   <%#  Add some other content, or use a different template: %>
+      #  And in other place:
       #
       #   <% content_for :navigation do %>
       #     <li><%= link_to 'Login', action: 'login' %></li>
@@ -145,8 +144,7 @@ def capture(*args)
       #
       #   <% content_for :script, javascript_include_tag(:defaults) %>
       #
-      # WARNING: content_for is ignored in caches. So you shouldn't use it
-      # for elements that will be fragment cached.
+      # WARNING: content_for is ignored in caches. So you shouldn't use it for elements that will be fragment cached.
       def content_for(name, content = nil, options = {}, &block)
         if content || block_given?
           if block_given?
@@ -173,13 +171,9 @@ def provide(name, content = nil, &block)
         result unless content
       end
 
-      # content_for? simply checks whether any content has been captured yet using content_for
+      # content_for? checks whether any content has been captured yet using `content_for`.
       # Useful to render parts of your layout differently based on what is in your views.
       #
-      # ==== Examples
-      #
-      # Perhaps you will use different css in you layout if no content_for :right_column
-      #
       #   <%# This is the layout %>
       #   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
       #   <head>

actionpack/lib/action_view/helpers/date_helper.rb

@@ -45,7 +45,6 @@ module DateHelper
       #   40-59 secs      # => less than a minute
       #   60-89 secs      # => 1 minute
       #
-      # ==== Examples
       #   from_time = Time.now
       #   distance_of_time_in_words(from_time, from_time + 50.minutes)                                # => about 1 hour
       #   distance_of_time_in_words(from_time, 50.minutes.from_now)                                   # => about 1 hour
@@ -166,7 +165,6 @@ def time_ago_in_words(from_time, include_seconds_or_options = {})
       # Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based
       # attribute (identified by +method+) on an object assigned to the template (identified by +object+).
       #
-      #
       # ==== Options
       # * <tt>:use_month_numbers</tt> - Set to true if you want to use month numbers rather than month names (e.g.
       #   "2" instead of "February").

actionpack/lib/action_view/helpers/form_helper.rb

@@ -460,8 +460,6 @@ def apply_form_for_options!(record, object, options) #:nodoc:
       # doesn't create the form tags themselves. This makes fields_for suitable
       # for specifying additional model objects in the same form.
       #
-      # === Generic Examples
-      #
       # Although the usage and purpose of +field_for+ is similar to +form_for+'s,
       # its method signature is slightly different. Like +form_for+, it yields
       # a FormBuilder object associated with a particular model object to a block,

actionpack/lib/action_view/helpers/form_options_helper.rb

@@ -7,13 +7,11 @@ module ActionView
   # = Action View Form Option Helpers
   module Helpers
     # Provides a number of methods for turning different kinds of containers into a set of option tags.
-    # == Options
+    #
     # The <tt>collection_select</tt>, <tt>select</tt> and <tt>time_zone_select</tt> methods take an <tt>options</tt> parameter, a hash:
     #
     # * <tt>:include_blank</tt> - set to true or a prompt string if the first option element of the select element is a blank. Useful if there is not a default value required for the select element.
     #
-    # For example,
-    #
     #   select("post", "category", Post::CATEGORIES, {include_blank: true})
     #
     # could become:
@@ -24,7 +22,7 @@ module Helpers
     #     <option>poem</option>
     #   </select>
     #
-    # Another common case is a select tag for an <tt>belongs_to</tt>-associated object.
+    # Another common case is a select tag for a <tt>belongs_to</tt>-associated object.
     #
     # Example with @post.person_id => 2:
     #
@@ -41,8 +39,6 @@ module Helpers
     #
     # * <tt>:prompt</tt> - set to true or a prompt string. When the select element doesn't have a value yet, this prepends an option with a generic prompt -- "Please select" -- or the given prompt string.
     #
-    # Example:
-    #
     #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, {prompt: 'Select Person'})
     #
     # could become:
@@ -57,8 +53,6 @@ module Helpers
     # Like the other form helpers, +select+ can accept an <tt>:index</tt> option to manually set the ID used in the resulting output. Unlike other helpers, +select+ expects this
     # option to be in the +html_options+ parameter.
     #
-    # Example:
-    #
     #   select("album[]", "genre", %w[rap rock country], {}, { index: nil })
     #
     # becomes:
@@ -71,8 +65,6 @@ module Helpers
     #
     # * <tt>:disabled</tt> - can be a single value or an array of values that will be disabled options in the final output.
     #
-    # Example:
-    #
     #   select("post", "category", Post::CATEGORIES, {disabled: 'restricted'})
     #
     # could become:
@@ -86,8 +78,6 @@ module Helpers
     #
     # When used with the <tt>collection_select</tt> helper, <tt>:disabled</tt> can also be a Proc that identifies those options that should be disabled.
     #
-    # Example:
-    #
     #   collection_select(:post, :category_id, Category.all, :id, :name, {disabled: lambda{|category| category.archived? }})
     #
     # If the categories "2008 stuff" and "Christmas" return true when the method <tt>archived?</tt> is called, this would return:
@@ -152,7 +142,8 @@ module FormOptionsHelper
       # form, and parameters extraction gets the last occurrence of any repeated
       # key in the query string, that works for ordinary forms.
       #
-      # In case if you don't want the helper to generate this hidden field you can specify <tt>include_hidden: false</tt> option.
+      # In case if you don't want the helper to generate this hidden field you can specify
+      # <tt>include_hidden: false</tt> option.
       #
       def select(object, method, choices, options = {}, html_options = {})
         Tags::Select.new(object, method, self, choices, options, html_options).render
@@ -170,9 +161,11 @@ def select(object, method, choices, options = {}, html_options = {})
       # retrieve the value/text.
       #
       # Example object structure for use with this method:
+      #
       #   class Post < ActiveRecord::Base
       #     belongs_to :author
       #   end
+      #
       #   class Author < ActiveRecord::Base
       #     has_many :posts
       #     def name_with_initial
@@ -181,6 +174,7 @@ def select(object, method, choices, options = {}, html_options = {})
       #   end
       #
       # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>):
+      #
       #   collection_select(:post, :author_id, Author.all, :id, :name_with_initial, prompt: true)
       #
       # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return:
@@ -213,23 +207,28 @@ def collection_select(object, method, collection, value_method, text_method, opt
       #   +collection+, returns a value to be used as the contents of its <tt><option></tt> tag.
       #
       # Example object structure for use with this method:
+      #
       #   class Continent < ActiveRecord::Base
       #     has_many :countries
       #     # attribs: id, name
       #   end
+      #
       #   class Country < ActiveRecord::Base
       #     belongs_to :continent
       #     # attribs: id, name, continent_id
       #   end
+      #
       #   class City < ActiveRecord::Base
       #     belongs_to :country
       #     # attribs: id, name, country_id
       #   end
       #
       # Sample usage:
+      #
       #   grouped_collection_select(:city, :country_id, @continents, :countries, :name, :id, :name)
       #
       # Possible output:
+      #
       #   <select name="city[country_id]">
       #     <optgroup label="Africa">
       #       <option value="1">South Africa</option>
@@ -284,57 +283,54 @@ def time_zone_select(object, method, priority_zones = nil, options = {}, html_op
       # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag. +selected+
       # may also be an array of values to be selected when using a multiple select.
       #
-      # Examples (call, result):
       #   options_for_select([["Dollar", "$"], ["Kroner", "DKK"]])
-      #   # <option value="$">Dollar</option>
-      #   # <option value="DKK">Kroner</option>
+      #   # => <option value="$">Dollar</option>
+      #   # => <option value="DKK">Kroner</option>
       #
       #   options_for_select([ "VISA", "MasterCard" ], "MasterCard")
-      #   # <option>VISA</option>
-      #   # <option selected="selected">MasterCard</option>
+      #   # => <option>VISA</option>
+      #   # => <option selected="selected">MasterCard</option>
       #
       #   options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
-      #   # <option value="$20">Basic</option>
-      #   # <option value="$40" selected="selected">Plus</option>
+      #   # => <option value="$20">Basic</option>
+      #   # => <option value="$40" selected="selected">Plus</option>
       #
       #   options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"])
-      #   # <option selected="selected">VISA</option>
-      #   # <option>MasterCard</option>
-      #   # <option selected="selected">Discover</option>
+      #   # => <option selected="selected">VISA</option>
+      #   # => <option>MasterCard</option>
+      #   # => <option selected="selected">Discover</option>
       #
       # You can optionally provide html attributes as the last element of the array.
       #
-      # Examples:
       #   options_for_select([ "Denmark", ["USA", {class: 'bold'}], "Sweden" ], ["USA", "Sweden"])
-      #   # <option value="Denmark">Denmark</option>
-      #   # <option value="USA" class="bold" selected="selected">USA</option>
-      #   # <option value="Sweden" selected="selected">Sweden</option>
+      #   # => <option value="Denmark">Denmark</option>
+      #   # => <option value="USA" class="bold" selected="selected">USA</option>
+      #   # => <option value="Sweden" selected="selected">Sweden</option>
       #
       #   options_for_select([["Dollar", "$", {class: "bold"}], ["Kroner", "DKK", {onclick: "alert('HI');"}]])
-      #   # <option value="$" class="bold">Dollar</option>
-      #   # <option value="DKK" onclick="alert('HI');">Kroner</option>
+      #   # => <option value="$" class="bold">Dollar</option>
+      #   # => <option value="DKK" onclick="alert('HI');">Kroner</option>
       #
       # If you wish to specify disabled option tags, set +selected+ to be a hash, with <tt>:disabled</tt> being either a value
       # or array of values to be disabled. In this case, you can use <tt>:selected</tt> to specify selected option tags.
       #
-      # Examples:
       #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], disabled: "Super Platinum")
-      #   # <option value="Free">Free</option>
-      #   # <option value="Basic">Basic</option>
-      #   # <option value="Advanced">Advanced</option>
-      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   # => <option value="Free">Free</option>
+      #   # => <option value="Basic">Basic</option>
+      #   # => <option value="Advanced">Advanced</option>
+      #   # => <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], disabled: ["Advanced", "Super Platinum"])
-      #   # <option value="Free">Free</option>
-      #   # <option value="Basic">Basic</option>
-      #   # <option value="Advanced" disabled="disabled">Advanced</option>
-      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   # => <option value="Free">Free</option>
+      #   # => <option value="Basic">Basic</option>
+      #   # => <option value="Advanced" disabled="disabled">Advanced</option>
+      #   # => <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], selected: "Free", disabled: "Super Platinum")
-      #   # <option value="Free" selected="selected">Free</option>
-      #   # <option value="Basic">Basic</option>
-      #   # <option value="Advanced">Advanced</option>
-      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   # => <option value="Free" selected="selected">Free</option>
+      #   # => <option value="Basic">Basic</option>
+      #   # => <option value="Advanced">Advanced</option>
+      #   # => <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
       def options_for_select(container, selected = nil)
@@ -358,12 +354,12 @@ def options_for_select(container, selected = nil)
 
       # Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning
       # the result of a call to the +value_method+ as the option value and the +text_method+ as the option text.
-      # Example:
+      #
       #   options_from_collection_for_select(@people, 'id', 'name')
-      # This will output the same HTML as if you did this:
-      #   <option value="#{person.id}">#{person.name}</option>
+      #   # => <option value="#{person.id}">#{person.name}</option>
       #
       # This is more often than not used inside a #select_tag like this example:
+      #
       #   select_tag 'person', options_from_collection_for_select(@people, 'id', 'name')
       #
       # If +selected+ is specified as a value or array of values, the element(s) returning a match on +value_method+
@@ -412,10 +408,12 @@ def options_from_collection_for_select(collection, value_method, text_method, se
       #   to be specified.
       #
       # Example object structure for use with this method:
+      #
       #   class Continent < ActiveRecord::Base
       #     has_many :countries
       #     # attribs: id, name
       #   end
+      #
       #   class Country < ActiveRecord::Base
       #     belongs_to :continent
       #     # attribs: id, name, continent_id
@@ -465,7 +463,6 @@ def option_groups_from_collection_for_select(collection, group_method, group_lab
       #   prepends an option with a generic prompt - "Please select" - or the given prompt string.
       # * <tt>:divider</tt> - the divider for the options groups.
       #
-      # Sample usage (Array):
       #   grouped_options = [
       #    ['North America',
       #      [['United States','US'],'Canada']],
@@ -474,7 +471,6 @@ def option_groups_from_collection_for_select(collection, group_method, group_lab
       #   ]
       #   grouped_options_for_select(grouped_options)
       #
-      # Sample usage (Hash):
       #   grouped_options = {
       #     'North America' => [['United States','US'], 'Canada'],
       #     'Europe' => ['Denmark','Germany','France']
@@ -492,7 +488,6 @@ def option_groups_from_collection_for_select(collection, group_method, group_lab
       #     <option value="France">France</option>
       #   </optgroup>
       #
-      # Sample usage (divider):
       #   grouped_options = [
       #     [['United States','US'], 'Canada'],
       #     ['Denmark','Germany','France']

actionpack/lib/action_view/helpers/javascript_helper.rb

@@ -18,7 +18,8 @@ module JavaScriptHelper
 
       # Escapes carriage returns and single and double quotes for JavaScript segments.
       #
-      # Also available through the alias j(). This is particularly helpful in JavaScript responses, like:
+      # Also available through the alias j(). This is particularly helpful in JavaScript
+      # responses, like:
       #
       #   $('some_element').replaceWith('<%=j render 'some/element_template' %>');
       def escape_javascript(javascript)
@@ -43,12 +44,14 @@ def escape_javascript(javascript)
       #   </script>
       #
       # +html_options+ may be a hash of attributes for the <tt>\<script></tt>
-      # tag. Example:
+      # tag.
+      #
       #   javascript_tag "alert('All is good')", defer: 'defer'
       #   # => <script defer="defer">alert('All is good')</script>
       #
       # Instead of passing the content as an argument, you can also use a block
       # in which case, you pass your +html_options+ as the first parameter.
+      #
       #   <%= javascript_tag defer: 'defer' do -%>
       #     alert('All is good')
       #   <% end -%>

actionpack/lib/action_view/helpers/output_safety_helper.rb

@@ -11,7 +11,8 @@ module OutputSafetyHelper
       #
       # For example:
       #
-      # <%=raw @user.name %>
+      #  raw @user.name
+      #  # => 'Jimmy <alert>Tables</alert>'
       def raw(stringish)
         stringish.to_s.html_safe
       end

actionpack/lib/action_view/helpers/sanitize_helper.rb

@@ -3,7 +3,7 @@
 
 module ActionView
   # = Action View Sanitize Helpers
-  module Helpers #:nodoc:
+  module Helpers
     # The SanitizeHelper module provides a set of methods for scrubbing text of undesired HTML elements.
     # These helper methods extend Action View making them callable within your template files.
     module SanitizeHelper

actionpack/lib/action_view/railtie.rb

@@ -3,7 +3,7 @@
 
 module ActionView
   # = Action View Railtie
-  class Railtie < Rails::Railtie
+  class Railtie < Rails::Railtie # :nodoc:
     config.action_view = ActiveSupport::OrderedOptions.new
     config.action_view.embed_authenticity_token_in_remote_forms = false
 

activerecord/lib/active_record/autosave_association.rb

@@ -32,8 +32,6 @@ module ActiveRecord
   # autosave callbacks are executed. Placing your callbacks after
   # associations is usually a good practice.
   #
-  # == Examples
-  #
   # === One-to-one Example
   #
   #   class Post

activerecord/lib/active_record/counter_cache.rb

@@ -79,16 +79,17 @@ def update_counters(id, counters)
         where(primary_key => id).update_all updates.join(', ')
       end
 
-      # Increment a number field by one, usually representing a count.
+      # Increment a numeric field by one, via a direct SQL update.
       #
-      # This is used for caching aggregate values, so that they don't need to be computed every time.
-      # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
-      # shown it would have to run an SQL query to find how many posts and comments there are.
+      # This method is used primarily for maintaining counter_cache columns used to
+      # store aggregate values. For example, a DiscussionBoard may cache posts_count
+      # and comments_count to avoid running an SQL query to calculate the number of
+      # posts and comments there are each time it is displayed.
       #
       # ==== Parameters
       #
       # * +counter_name+ - The name of the field that should be incremented.
-      # * +id+ - The id of the object that should be incremented.
+      # * +id+ - The id of the object that should be incremented or an Array of ids.
       #
       # ==== Examples
       #
@@ -98,14 +99,15 @@ def increment_counter(counter_name, id)
         update_counters(id, counter_name => 1)
       end
 
-      # Decrement a number field by one, usually representing a count.
+      # Decrement a numeric field by one, via a direct SQL update.
       #
-      # This works the same as increment_counter but reduces the column value by 1 instead of increasing it.
+      # This works the same as increment_counter but reduces the column value by
+      # 1 instead of increasing it.
       #
       # ==== Parameters
       #
       # * +counter_name+ - The name of the field that should be decremented.
-      # * +id+ - The id of the object that should be decremented.
+      # * +id+ - The id of the object that should be decremented or an Array of ids.
       #
       # ==== Examples
       #

activerecord/lib/active_record/integration.rb

@@ -29,8 +29,6 @@ def to_param
 
     # Returns a cache key that can be used to identify this record.
     #
-    # ==== Examples
-    #
     #   Product.new.cache_key     # => "products/new"
     #   Product.find(5).cache_key # => "products/5" (updated_at not available)
     #   Person.find(5).cache_key  # => "people/5-20071224150000" (updated_at available)

activerecord/lib/active_record/query_cache.rb

@@ -4,6 +4,7 @@ module ActiveRecord
   class QueryCache
     module ClassMethods
       # Enable the query cache within the block if Active Record is configured.
+      # If it's not, it will execute the given block.
       def cache(&block)
         if ActiveRecord::Base.connected?
           connection.cache(&block)
@@ -13,6 +14,7 @@ def cache(&block)
       end
 
       # Disable the query cache within the block if Active Record is configured.
+      # If it's not, it will execute the given block.
       def uncached(&block)
         if ActiveRecord::Base.connected?
           connection.uncached(&block)

activerecord/lib/active_record/querying.rb

@@ -26,14 +26,13 @@ module Querying
     # MySQL specific terms will lock you to using that particular database engine or require you to
     # change your call if you switch engines.
     #
-    # ==== Examples
     #   # A simple SQL query spanning multiple tables
     #   Post.find_by_sql "SELECT p.title, c.author FROM posts p, comments c WHERE p.id = c.post_id"
-    #   > [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...]
+    #   # => [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...]
     #
     #   # You can use the same string replacement techniques as you can with ActiveRecord#find
     #   Post.find_by_sql ["SELECT title FROM posts WHERE author = ? AND created > ?", author_id, start_date]
-    #   > [#<Post:0x36bff9c @attributes={"title"=>"The Cheap Man Buys Twice"}>, ...]
+    #   # => [#<Post:0x36bff9c @attributes={"title"=>"The Cheap Man Buys Twice"}>, ...]
     def find_by_sql(sql, binds = [])
       logging_query_plan do
         result_set = connection.select_all(sanitize_sql(sql), "#{name} Load", binds)
@@ -57,8 +56,6 @@ def find_by_sql(sql, binds = [])
     #
     # * +sql+ - An SQL statement which should return a count query from the database, see the example below.
     #
-    # ==== Examples
-    #
     #   Product.count_by_sql "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id = c.id"
     def count_by_sql(sql)
       logging_query_plan do

activerecord/lib/active_record/relation/calculations.rb

@@ -76,18 +76,17 @@ def sum(*args)
     #
     #       values = Person.group('last_name').maximum(:age)
     #       puts values["Drake"]
-    #       => 43
+    #       # => 43
     #
     #       drake  = Family.find_by_last_name('Drake')
     #       values = Person.group(:family).maximum(:age) # Person belongs_to :family
     #       puts values[drake]
-    #       => 43
+    #       # => 43
     #
     #       values.each do |family, max_age|
     #       ...
     #       end
     #
-    # Examples:
     #   Person.calculate(:count, :all) # The same as Person.count
     #   Person.average(:age) # SELECT AVG(age) FROM people...
     #
@@ -124,8 +123,6 @@ def calculate(operation, column_name, options = {})
     # the plucked column names, if they can be deduced. Plucking an SQL fragment
     # returns String values by default.
     #
-    # Examples:
-    #
     #   Person.pluck(:id)
     #   # SELECT people.id FROM people
     #   # => [1, 2, 3]
@@ -182,8 +179,6 @@ def pluck(*column_names)
 
     # Pluck all the ID's for the relation using the table's primary key
     #
-    # Examples:
-    #
     #   Person.ids # SELECT people.id FROM people
     #   Person.joins(:companies).ids # SELECT people.id FROM people INNER JOIN companies ON companies.person_id = people.id
     def ids

activerecord/lib/active_record/relation/spawn_methods.rb

@@ -12,9 +12,6 @@ def spawn #:nodoc:
 
     # Merges in the conditions from <tt>other</tt>, if <tt>other</tt> is an <tt>ActiveRecord::Relation</tt>.
     # Returns an array representing the intersection of the resulting records with <tt>other</tt>, if <tt>other</tt> is an array.
-    #
-    # ==== Examples
-    #
     #   Post.where(published: true).joins(:comments).merge( Comment.where(spam: false) )
     #   # Performs a single join query with both where conditions.
     #
@@ -29,7 +26,6 @@ def spawn #:nodoc:
     #   # => Post.where(published: true).joins(:comments)
     #
     # This is mainly intended for sharing common conditions between multiple associations.
-    #
     def merge(other)
       if other.is_a?(Array)
         to_a & other
@@ -51,11 +47,8 @@ def merge!(other) # :nodoc:
 
     # Removes from the query the condition(s) specified in +skips+.
     #
-    # Example:
-    #
     #   Post.order('id asc').except(:order)                  # discards the order condition
     #   Post.where('id > 10').order('id asc').except(:where) # discards the where condition but keeps the order
-    #
     def except(*skips)
       result = Relation.new(klass, table, values.except(*skips))
       result.default_scoped = default_scoped
@@ -65,11 +58,8 @@ def except(*skips)
 
     # Removes any condition from the query other than the one(s) specified in +onlies+.
     #
-    # Example:
-    #
     #   Post.order('id asc').only(:where)         # discards the order condition
     #   Post.order('id asc').only(:where, :order) # uses the specified order
-    #
     def only(*onlies)
       result = Relation.new(klass, table, values.slice(*onlies))
       result.default_scoped = default_scoped

activerecord/lib/active_record/schema.rb

@@ -29,11 +29,16 @@ module ActiveRecord
   # ActiveRecord::Schema is only supported by database adapters that also
   # support migrations, the two features being very similar.
   class Schema < Migration
+
+    # Returns the migrations paths.
+    #
+    #   ActiveRecord::Schema.new.migrations_paths
+    #   # => ["db/migrate"] # Rails migration path by default.
     def migrations_paths
       ActiveRecord::Migrator.migrations_paths
     end
 
-    def define(info, &block)
+    def define(info, &block) # :nodoc:
       instance_eval(&block)
 
       unless info[:version].blank?

activesupport/lib/active_support/core_ext/hash/conversions.rb

@@ -88,6 +88,19 @@ def to_xml(options = {})
   end
 
   class << self
+    # Returns a Hash containing a collection of pairs when the key is the node name and the value is
+    # its content
+    #
+    #   xml = <<-XML
+    #     <?xml version="1.0" encoding="UTF-8"?>
+    #       <hash>
+    #         <foo type="integer">1</foo>
+    #         <bar type="integer">2</bar>
+    #       </hash>
+    #   XML
+    #
+    #   hash = Hash.from_xml(xml)
+    #   # => {"hash"=>{"foo"=>1, "bar"=>2}}
     def from_xml(xml)
       typecast_xml_value(unrename_keys(ActiveSupport::XmlMini.parse(xml)))
     end

activesupport/lib/active_support/testing/constant_lookup.rb

@@ -30,7 +30,7 @@ module Testing
     module ConstantLookup
       extend ::ActiveSupport::Concern
 
-      module ClassMethods
+      module ClassMethods  # :nodoc:
         def determine_constant_from_test_name(test_name)
           names = test_name.split "::"
           while names.size > 0 do

activesupport/lib/active_support/testing/pending.rb

@@ -2,8 +2,8 @@
 
 module ActiveSupport
   module Testing
-    module Pending
-      unless defined?(Spec)
+    module Pending # :nodoc:
+      unless defined?(Spec) 
         def pending(description = "", &block)
           ActiveSupport::Deprecation.warn("#pending is deprecated and will be removed in Rails 4.1, please use #skip instead.")
           skip(description.blank? ? nil : description)

guides/source/getting_started.md

@@ -520,7 +520,7 @@ invoking the command: `rake db:migrate RAILS_ENV=production`.
 ### Saving data in the controller
 
 Back in `posts_controller`, we need to change the `create` action
-to use the new `Post` model to save the data in the database. Open that file
+to use the new `Post` model to save the data in the database. Open `app/controllers/posts_controller.rb`
 and change the `create` action to look like this:
 
 ```ruby
@@ -558,8 +558,8 @@ parameter, which in our case will be the id of the post. Note that this
 time we had to specify the actual mapping, `posts#show` because
 otherwise Rails would not know which action to render.
 
-As we did before, we need to add the `show` action in the
-`posts_controller` and its respective view.
+As we did before, we need to add the `show` action in 
+`app/controllers/posts_controller.rb` and its respective view.
 
 ```ruby
 def show
@@ -1216,7 +1216,7 @@ This command will generate four files:
 | test/models/comment_test.rb                  | Testing harness for the comments model                                                                 |
 | test/fixtures/comments.yml                   | Sample comments for use in testing                                                                     |
 
-First, take a look at `comment.rb`:
+First, take a look at `app/models/comment.rb`:
 
 ```ruby
 class Comment < ActiveRecord::Base
@@ -1277,7 +1277,7 @@ this way:
 * One post can have many comments.
 
 In fact, this is very close to the syntax that Rails uses to declare this
-association. You've already seen the line of code inside the `Comment` model that
+association. You've already seen the line of code inside the `Comment` model (app/models/comment.rb) that
 makes each comment belong to a Post:
 
 ```ruby
@@ -1286,7 +1286,7 @@ class Comment < ActiveRecord::Base
 end
 ```
 
-You'll need to edit the `post.rb` file to add the other side of the association:
+You'll need to edit `app/models/post.rb` to add the other side of the association:
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -1350,7 +1350,7 @@ the post show page to see their comment now listed. Due to this, our
 spam comments when they arrive.
 
 So first, we'll wire up the Post show template
-(`/app/views/posts/show.html.erb`) to let us make a new comment:
+(`app/views/posts/show.html.erb`) to let us make a new comment:
 
 ```html+erb
 <p>
@@ -1609,7 +1609,7 @@ So first, let's add the delete link in the
 Clicking this new "Destroy Comment" link will fire off a `DELETE
 /posts/:post_id/comments/:id` to our `CommentsController`, which can then use
 this to find the comment we want to delete, so let's add a destroy action to our
-controller:
+controller (`app/controllers/comments_controller.rb`):
 
 ```ruby
 class CommentsController < ApplicationController
@@ -1667,7 +1667,7 @@ action if that method allows it.
 
 To use the authentication system, we specify it at the top of our
 `PostsController`, in this case, we want the user to be authenticated on every
-action, except for `index` and `show`, so we write that:
+action, except for `index` and `show`, so we write that in `app/controllers/posts_controller.rb`:
 
 ```ruby
 class PostsController < ApplicationController
@@ -1682,7 +1682,7 @@ class PostsController < ApplicationController
 ```
 
 We also only want to allow authenticated users to delete comments, so in the
-`CommentsController` we write:
+`CommentsController` (`app/controllers/comments_controller.rb`) we write:
 
 ```ruby
 class CommentsController < ApplicationController

guides/source/i18n.md

@@ -696,7 +696,7 @@ en:
       long: "%B %d, %Y"
 ```
 
-So, all of the following equivalent lookups will return the `:short` date format `"%B %d"`:
+So, all of the following equivalent lookups will return the `:short` date format `"%b %d"`:
 
 ```ruby
 I18n.t 'date.formats.short'

guides/source/migrations.md

@@ -433,7 +433,7 @@ no such migrations, it exits. It will run these migrations in order based
 on the date of the migration.
 
 Note that running the `db:migrate` also invokes the `db:schema:dump` task, which
-will update your db/schema.rb file to match the structure of your database.
+will update your `db/schema.rb` file to match the structure of your database.
 
 If you specify a target version, Active Record will run the required migrations
 (up, down or change) until it has reached the specified version. The version

guides/source/ruby_on_rails_guides_guidelines.md

@@ -62,7 +62,7 @@ HTML Guides
 
 ### Generation
 
-To generate all the guides, just `cd` into the **`guides`** directory and execute:
+To generate all the guides, just `cd` into the **`guides`** directory, run `bundle install` and execute:
 
 ```
 bundle exec rake guides:generate
@@ -74,8 +74,6 @@ or
 bundle exec rake guides:generate:html
 ```
 
-(You may need to run `bundle install` first to install the required gems.)
-
 To process `my_guide.md` and nothing else use the `ONLY` environment variable:
 
 ```