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

Conflicts: guides/source/migrations.md

Merge branch 'master' of github.com:lifo/docrails
Conflicts: guides/source/migrations.md
40e16121 · Vijay Dev · 9d3ce6c7 · 2b847a0a · 40e16121 · 40e16121
39 changed file
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/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'

--- a/actionpack/lib/abstract_controller/helpers.rb
+++ b/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
      #

--- a/actionpack/lib/action_controller/caching.rb
+++ b/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
+  # You can read more about each approach by clicking the modules below.
-  # modules below.
  #
  # Note: To turn off all caching, set
  #   config.action_controller.perform_caching = false.

--- a/actionpack/lib/action_controller/metal/streaming.rb
+++ b/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.
  #

--- a/actionpack/lib/action_dispatch/middleware/flash.rb
+++ b/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

--- a/actionpack/lib/action_dispatch/railtie.rb
+++ b/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

--- a/actionpack/lib/action_dispatch/routing.rb
+++ b/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'
  #

--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/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

--- a/actionpack/lib/action_dispatch/routing/polymorphic_routes.rb
+++ b/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)
      #

--- a/actionpack/lib/action_dispatch/testing/assertions/selector.rb
+++ b/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"
      #

--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/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
-      #  auto_discovery_link_tag
+      #   # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/action" />
-      #  # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/action" />
+      #   auto_discovery_link_tag(:atom)
-      #  auto_discovery_link_tag(:atom)
+      #   # => <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.currenthost.com/controller/action" />
-      #  # => <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.currenthost.com/controller/action" />
+      #   auto_discovery_link_tag(:rss, {action: "feed"})
-      #  auto_discovery_link_tag(:rss, {action: "feed"})
+      #   # => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/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"})
-      #  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" />
-      #  # => <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"})
-      #  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" />
-      #  # => <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"})
-      #  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" />
-      #  # => <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 %>
+      # 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
-      # generates
+      # you can override "rel" and "type".
-      #
-      #   <link href="/assets/favicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon" />
-      #
-      # You may specify a different file in the first argument:
      #
-      #   <%= favicon_link_tag '/myicon.ico' %>
+      # ==== Options
-      #
+      # * <tt>:rel</tt>   - Specify the relation of this link, defaults to 'shortcut icon'
-      # That's passed to +path_to_image+ as is, so it gives
+      # * <tt>:type</tt>  - Override the auto-generated mime type, defaults to 'image/vnd.microsoft.icon'
-      #
-      #   <link href="/myicon.ico" rel="shortcut icon" type="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")
+      #   image_tag("icon")
-      #  # => <img alt="Icon" src="/assets/icon" />
+      #   # => <img alt="Icon" src="/assets/icon" />
-      #  image_tag("icon.png")
+      #   image_tag("icon.png")
-      #  # => <img alt="Icon" src="/assets/icon.png" />
+      #   # => <img alt="Icon" src="/assets/icon.png" />
-      #  image_tag("icon.png", size: "16x10", alt: "Edit Entry")
+      #   image_tag("icon.png", size: "16x10", alt: "Edit Entry")
-      #  # => <img src="/assets/icon.png" width="16" height="10" alt="Edit Entry" />
+      #   # => <img src="/assets/icon.png" width="16" height="10" alt="Edit Entry" />
-      #  image_tag("/icons/icon.gif", size: "16")
+      #   image_tag("/icons/icon.gif", size: "16")
-      #  # => <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
+      #   # => <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
-      #  image_tag("/icons/icon.gif", height: '32', width: '32')
+      #   image_tag("/icons/icon.gif", height: '32', width: '32')
-      #  # => <img alt="Icon" height="32" src="/icons/icon.gif" width="32" />
+      #   # => <img alt="Icon" height="32" src="/icons/icon.gif" width="32" />
-      #  image_tag("/icons/icon.gif", class: "menu_icon")
+      #   image_tag("/icons/icon.gif", class: "menu_icon")
-      #  # => <img alt="Icon" class="menu_icon" src="/icons/icon.gif" />
+      #   # => <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_tag("trailer")
-      #  # => <video src="/videos/trailer" />
+      #   # => <video src="/videos/trailer" />
-      #  video_tag("trailer.ogg")
+      #   video_tag("trailer.ogg")
-      #  # => <video src="/videos/trailer.ogg" />
+      #   # => <video src="/videos/trailer.ogg" />
-      #  video_tag("trailer.ogg", controls: true, autobuffer: true)
+      #   video_tag("trailer.ogg", controls: true, autobuffer: true)
-      #  # => <video autobuffer="autobuffer" controls="controls" src="/videos/trailer.ogg" />
+      #   # => <video autobuffer="autobuffer" controls="controls" src="/videos/trailer.ogg" />
-      #  video_tag("trailer.m4v", size: "16x10", poster: "screenshot.png")
+      #   video_tag("trailer.m4v", size: "16x10", poster: "screenshot.png")
-      #  # => <video src="/videos/trailer.m4v" width="16" height="10" poster="/assets/screenshot.png" />
+      #   # => <video src="/videos/trailer.m4v" width="16" height="10" poster="/assets/screenshot.png" />
-      #  video_tag("/trailers/hd.avi", size: "16x16")
+      #   video_tag("/trailers/hd.avi", size: "16x16")
-      #  # => <video src="/trailers/hd.avi" width="16" height="16" />
+      #   # => <video src="/trailers/hd.avi" width="16" height="16" />
-      #  video_tag("/trailers/hd.avi", height: '32', width: '32')
+      #   video_tag("/trailers/hd.avi", height: '32', width: '32')
-      #  # => <video height="32" src="/trailers/hd.avi" width="32" />
+      #   # => <video height="32" src="/trailers/hd.avi" width="32" />
-      #  video_tag("trailer.ogg", "trailer.flv")
+      #   video_tag("trailer.ogg", "trailer.flv")
-      #  # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
+      #   # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
-      #  video_tag(["trailer.ogg", "trailer.flv"])
+      #   video_tag(["trailer.ogg", "trailer.flv"])
-      #  # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
+      #   # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
-      #  video_tag(["trailer.ogg", "trailer.flv"], size: "160x120")
+      #   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 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_tag("sound")
-      #     <audio src="/audios/sound" />
+      #   # => <audio src="/audios/sound" />
-      #   audio_tag("sound.wav")  # =>
+      #   audio_tag("sound.wav")
-      #     <audio src="/audios/sound.wav" />
+      #   # => <audio src="/audios/sound.wav" />
-      #   audio_tag("sound.wav", autoplay: true, controls: true)  # =>
+      #   audio_tag("sound.wav", autoplay: true, controls: true)
-      #     <audio autoplay="autoplay" controls="controls" src="/audios/sound.wav" />
+      #   # => <audio autoplay="autoplay" controls="controls" src="/audios/sound.wav" />
-      #   audio_tag("sound.wav", "sound.mid")  # =>
+      #   audio_tag("sound.wav", "sound.mid")
-      #     <audio><source src="/audios/sound.wav" /><source src="/audios/sound.mid" /></audio>
+      #   # => <audio><source src="/audios/sound.wav" /><source src="/audios/sound.mid" /></audio>
      def audio_tag(*sources)
        multiple_sources_tag('audio', sources)
      end

--- a/actionpack/lib/action_view/helpers/asset_url_helper.rb
+++ b/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.
    #

--- a/actionpack/lib/action_view/helpers/atom_feed_helper.rb
+++ b/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

--- a/actionpack/lib/action_view/helpers/benchmark_helper.rb
+++ b/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(*)

--- a/actionpack/lib/action_view/helpers/capture_helper.rb
+++ b/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
+      # In order to access this stored content in other templates, helper modules
-      # or the layout by passing the identifier as an argument to <tt>content_for</tt>.
+      # 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
+      # WARNING: content_for is ignored in caches. So you shouldn't use it for elements that will be fragment cached.
-      # 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>

--- a/actionpack/lib/action_view/helpers/date_helper.rb
+++ b/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").

--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/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,

--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/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="$">Dollar</option>
-      #   # <option value="DKK">Kroner</option>
+      #   # => <option value="DKK">Kroner</option>
      #
      #   options_for_select([ "VISA", "MasterCard" ], "MasterCard")
-      #   # <option>VISA</option>
+      #   # => <option>VISA</option>
-      #   # <option selected="selected">MasterCard</option>
+      #   # => <option selected="selected">MasterCard</option>
      #
      #   options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
-      #   # <option value="$20">Basic</option>
+      #   # => <option value="$20">Basic</option>
-      #   # <option value="$40" selected="selected">Plus</option>
+      #   # => <option value="$40" selected="selected">Plus</option>
      #
      #   options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"])
-      #   # <option selected="selected">VISA</option>
+      #   # => <option selected="selected">VISA</option>
-      #   # <option>MasterCard</option>
+      #   # => <option>MasterCard</option>
-      #   # <option selected="selected">Discover</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="Denmark">Denmark</option>
-      #   # <option value="USA" class="bold" selected="selected">USA</option>
+      #   # => <option value="USA" class="bold" selected="selected">USA</option>
-      #   # <option value="Sweden" selected="selected">Sweden</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="$" class="bold">Dollar</option>
-      #   # <option value="DKK" onclick="alert('HI');">Kroner</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="Free">Free</option>
-      #   # <option value="Basic">Basic</option>
+      #   # => <option value="Basic">Basic</option>
-      #   # <option value="Advanced">Advanced</option>
+      #   # => <option value="Advanced">Advanced</option>
-      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</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="Free">Free</option>
-      #   # <option value="Basic">Basic</option>
+      #   # => <option value="Basic">Basic</option>
-      #   # <option value="Advanced" disabled="disabled">Advanced</option>
+      #   # => <option value="Advanced" disabled="disabled">Advanced</option>
-      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</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="Free" selected="selected">Free</option>
-      #   # <option value="Basic">Basic</option>
+      #   # => <option value="Basic">Basic</option>
-      #   # <option value="Advanced">Advanced</option>
+      #   # => <option value="Advanced">Advanced</option>
-      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</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']

--- a/actionpack/lib/action_view/helpers/javascript_helper.rb
+++ b/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 -%>

--- a/actionpack/lib/action_view/helpers/number_helper.rb
+++ b/actionpack/lib/action_view/helpers/number_helper.rb
--- a/actionpack/lib/action_view/helpers/output_safety_helper.rb
+++ b/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

--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/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

--- a/actionpack/lib/action_view/railtie.rb
+++ b/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

--- a/activerecord/lib/active_record/autosave_association.rb
+++ b/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

--- a/activerecord/lib/active_record/counter_cache.rb
+++ b/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.
+      # This method is used primarily for maintaining counter_cache columns used to
-      # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
+      # store aggregate values. For example, a DiscussionBoard may cache posts_count
-      # shown it would have to run an SQL query to find how many posts and comments there are.
+      # 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
      #

--- a/activerecord/lib/active_record/integration.rb
+++ b/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)

--- a/activerecord/lib/active_record/query_cache.rb
+++ b/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)

--- a/activerecord/lib/active_record/querying.rb
+++ b/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

--- a/activerecord/lib/active_record/relation/calculations.rb
+++ b/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

--- a/activerecord/lib/active_record/relation/spawn_methods.rb
+++ b/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

--- a/activerecord/lib/active_record/schema.rb
+++ b/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?

--- a/activesupport/lib/active_support/core_ext/hash/conversions.rb
+++ b/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

--- a/activesupport/lib/active_support/testing/constant_lookup.rb
+++ b/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

--- a/activesupport/lib/active_support/testing/pending.rb
+++ b/activesupport/lib/active_support/testing/pending.rb
@@ -2,8 +2,8 @@
 module ActiveSupport
  module Testing
-    module Pending
+    module Pending # :nodoc:
-      unless defined?(Spec)
+      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)

--- a/guides/source/getting_started.md
+++ b/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
+As we did before, we need to add the `show` action in 
-`posts_controller` and its respective view.
+`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

--- a/guides/source/i18n.md
+++ b/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'

--- a/guides/source/migrations.md
+++ b/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

--- a/guides/source/routing.md
+++ b/guides/source/routing.md
--- a/guides/source/ruby_on_rails_guides_guidelines.md
+++ b/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:
 ```