The focus of this change is to make the API more accessible.
References to method and classes should be linked to make it easy to
navigate around.

This patch makes exzessiv use of `rdoc-ref:` to provide more readable
docs. This makes it possible to document `ActiveRecord::Base#save` even
though the method is within a separate module
`ActiveRecord::Persistence`. The goal here is to bring the API closer to
the actual code that you would write.

This commit only deals with Active Record. The other gems will be
updated accordingly but in different commits. The pass through Active
Record is not completely finished yet. A follow up commit will change
the spots I haven't yet had the time to update.

/cc @fxn

This error is raised in certain situations when eager loading
polymorphic associations. We even mention it in our docs. It should be
included in our API.

Conflicts:
	activerecord/lib/active_record/associations.rb

The **(11)** does not affect the storage size of the data type, which for an
INT will always be 4 bytes. It affects the **display width**.

http://www.tocker.ca/2015/07/02/proposal-to-deprecate-mysql-integer-display-width-and-zerofill.html

This change allows to instantiate all ActiveRecordError descendant
execption classes without arguments, which might be useful in testing
and is far less surprising than mandatory arguments.

There's a typo in ActiveRecord associations RDocs.
Wrong `Taggable` model name, instead of `Tagging` in example of using
option `:inverse_of` with `:belongs_to` association.

Commit where typo was introduced:
https://github.com/rails/rails/commit/91fd6510563f84ee473bb217bc63ed598abe3f24#diff-39001423802a8470dba9c931e66e101eR11

First it appears in `activerecord/CHANGELOG` in example of `:inverse_of`
usage:

```ruby
    class Post < ActiveRecord::Base
      has_many :taggings
      has_many :tags, :through => :taggings
    end

    class Tagging < ActiveRecord::Base
      belongs_to :post
      belongs_to :tag, :inverse_of => :tagging # :inverse_of must be set!
    end

    class Tag < ActiveRecord::Base
      has_many :taggings
      has_many :posts, :through => :taggings
    end

    post = Post.first
    tag = post.tags.build :name => "ruby"
!>  tag.save # will save a Taggable linking to the post
```

The last line should be

```ruby
    tag.save # will save a Tagging linking to the post
```

The same typo appears in
`activerecord/lib/active_record/associations.rb`.
The association name is given as `:inverse_of => :taggings`, but class
name is `Taggable`.

```ruby
    #   @post = Post.first
    #   @tag = @post.tags.build :name => "ruby"
    #   @tag.save
    #
!>  # The last line ought to save the through record (a <tt>Taggable</tt>). This will only work if the
    # <tt>:inverse_of</tt> is set:
    #
!>  #   class Taggable < ActiveRecord::Base
    #     belongs_to :post
!>  #     belongs_to :tag, :inverse_of => :taggings
    #   end
```

This PR fixes model name.

The examples now take in consideration when Active Record finds inverse
associations automatically.

See #9683 for the reasons we switched to `distinct`.

Here is the discussion that triggered the actual deprecation #20198.

`uniq`, `uniq!` and `uniq_value` are still around.
They will be removed in the next minor release after Rails 5.

we should ask the reflection for its name rather than storing the
reflection name in two places (an array and a reflection object)

the module name was changed in 8e814a0a

This will resolve the fixme message which is about making constant invisible.

Deprecate `required` option in favor of `optional` for belongs_to.

By default the foreign key will remain set with the parent id after
destroy is fired.

A model cannot have two `:belongs_to` with the same exact name, so
we are better off avoiding this code in our examples, which might
mislead users in thinking it's admissible.

[ci skip]

https://github.com/rails/rails/commit/5937bd02dee112646469848d7fe8a8bfcef5b4c1#commitcomment-9205786

To be possible to use a custom column name to save/read the polymorphic
associated type in a has_many or has_one polymorphic association, now users
can use the option :foreign_type to inform in what column the associated object
type will be saved.

Isolate access to @associations_cache and @aggregations cache to the Associations and Aggregations modules, respectively.

This includes replacing the `association_cache` accessor with a more
limited `association_cached?` accessor and making `clear_association_cache`
and `clear_aggregation_cache` private.

Previously the documentation stated that `primary_key` should be the name of
a *method* that returns the primary key used for the association. This is
incorrect. This changes the documentation to say that the value must be the
name of a column.

[ci skip]

Add improvements from @eileencodes [skip ci]