Cleans and removes useless 'Examples' tag [ci skip]

8 files changed, 46 insertions, 71 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index c9f10b359b..31005c9d9b 100644
--- 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'
diff --git a/actionpack/lib/abstract_controller/helpers.rb b/actionpack/lib/abstract_controller/helpers.rb
index d3929b685c..d4e73bf257 100644
--- a/actionpack/lib/abstract_controller/helpers.rb
+++ b/actionpack/lib/abstract_controller/helpers.rb
@@ -58,11 +58,10 @@ module AbstractController
 
       # 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
       #
diff --git a/actionpack/lib/action_controller/metal/streaming.rb b/actionpack/lib/action_controller/metal/streaming.rb
index 4eb582648e..0b3c438ec2 100644
--- 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.
   #
diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb
index 4417cb841a..d55eb8109a 100644
--- 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'
   #
diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index 0c19b493ab..d1645eea3a 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -624,8 +624,6 @@ module ActionDispatch
         #
         # 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 @@ module ActionDispatch
         # 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
diff --git a/actionpack/lib/action_dispatch/routing/polymorphic_routes.rb b/actionpack/lib/action_dispatch/routing/polymorphic_routes.rb
index 497ac3d545..6d3f8da932 100644
--- a/actionpack/lib/action_dispatch/routing/polymorphic_routes.rb
+++ b/actionpack/lib/action_dispatch/routing/polymorphic_routes.rb
@@ -74,8 +74,6 @@ module ActionDispatch
       # * <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)
       #
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 9310a90f0f..c0e7ee1f8d 100644
--- 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 ActionView
     #     <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 ActionView
     #
     # * <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 ActionView
     # 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 ActionView
     #
     # * <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 ActionView
     #
     # 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 ActionView
       # 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 @@ module ActionView
       # 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 @@ module ActionView
       #   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 @@ module ActionView
       #   +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 @@ module ActionView
       # 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 @@ module ActionView
 
       # 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 @@ module ActionView
       #   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 @@ module ActionView
       #   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 @@ module ActionView
       #   ]
       #   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 @@ module ActionView
       #     <option value="France">France</option>
       #   </optgroup>
       #
-      # Sample usage (divider):
       #   grouped_options = [
       #     [['United States','US'], 'Canada'],
       #     ['Denmark','Germany','France']
diff --git a/activerecord/lib/active_record/relation/calculations.rb b/activerecord/lib/active_record/relation/calculations.rb
index 99e77e007a..ccc14dddeb 100644
--- a/activerecord/lib/active_record/relation/calculations.rb
+++ b/activerecord/lib/active_record/relation/calculations.rb
@@ -76,18 +76,17 @@ module ActiveRecord
     #
     #       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 @@ module ActiveRecord
     # 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 @@ module ActiveRecord
 
     # 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