2 files changed, 89 insertions, 2 deletions

diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb
index 3b293baa73..9690f0ca28 100644
--- a/actionpack/lib/action_controller/metal/strong_parameters.rb
+++ b/actionpack/lib/action_controller/metal/strong_parameters.rb
@@ -112,6 +112,77 @@ module ActionController
 
     cattr_accessor :action_on_unpermitted_parameters, instance_accessor: false
 
+    ##
+    # :method: as_json
+    #
+    # :call-seq:
+    #   as_json(options=nil)
+    #
+    # Returns a hash that can be used as the JSON representation for the parameters.
+
+    ##
+    # :method: empty?
+    #
+    # :call-seq:
+    #   empty?()
+    #
+    # Returns true if the parameters have no key/value pairs.
+
+    ##
+    # :method: has_key?
+    #
+    # :call-seq:
+    #   has_key?(key)
+    #
+    # Returns true if the given key is present in the parameters.
+
+    ##
+    # :method: has_value?
+    #
+    # :call-seq:
+    #   has_value?(value)
+    #
+    # Returns true if the given value is present for some key in the parameters.
+
+    ##
+    # :method: include?
+    #
+    # :call-seq:
+    #   include?(key)
+    #
+    # Returns true if the given key is present in the parameters.
+
+    ##
+    # :method: key?
+    #
+    # :call-seq:
+    #   key?(key)
+    #
+    # Returns true if the given key is present in the parameters.
+
+    ##
+    # :method: keys
+    #
+    # :call-seq:
+    #   keys()
+    #
+    # Returns a new array of the keys of the parameters.
+
+    ##
+    # :method: value?
+    #
+    # :call-seq:
+    #   value?(value)
+    #
+    # Returns true if the given value is present for some key in the parameters.
+
+    ##
+    # :method: values
+    #
+    # :call-seq:
+    #   values()
+    #
+    # Returns a new array of the values of the parameters.
     delegate :keys, :key?, :has_key?, :values, :has_value?, :value?, :empty?, :include?,
       :as_json, to: :@parameters
 
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index 73c9c10c1f..5794bfa666 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -582,14 +582,30 @@ class CreateBooks < ActiveRecord::Migration[5.0]
       t.string   :book_number
       t.integer  :author_id
     end
-
-    add_index :books, :author_id
   end
 end
 ```
 
 If you create an association some time after you build the underlying model, you need to remember to create an `add_column` migration to provide the necessary foreign key.
 
+It's a good practice to add an index on the foreign key to improve queries
+performance and a foreign key constraint to ensure referential data integrity:
+
+```ruby
+class CreateBooks < ActiveRecord::Migration[5.0]
+  def change
+    create_table :books do |t|
+      t.datetime :published_at
+      t.string   :book_number
+      t.integer  :author_id
+    end
+    
+    add_index :books, :author_id
+    add_foreign_key :books, :authors
+  end
+end
+```
+
 #### Creating Join Tables for `has_and_belongs_to_many` Associations
 
 If you create a `has_and_belongs_to_many` association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the `:join_table` option, Active Record creates the name by using the lexical book of the class names. So a join between author and book models will give the default join table name of "authors_books" because "a" outranks "b" in lexical ordering.