- Followup of https://github.com/rails/rails/commit/71ff088a09d429657877ddfb58985d30df63fc8a

fixes #21500

The current example

    add_index :person_articles, :article, unique: true

Does not work, the `:article` column does not exist as it will be
a join table (based on the prior example) so should use :article_id

The documentation seems to suggest that it will allow an article to
be added only once to a person via the join table, what actually
occurs is that it only allows the article to be added to one person,
at which point it should be a `belongs_to` association.

Also changed the new example to use readings based on the prior example

This is a pass over the documentation which fills the missing gaps of
`ApplicationRecord`.

[ci skip]

Even though this means more things to change when we bump after a
release, it's more important that our examples are directly copyable.

If we use a real version, at best that'll be an onerous update required
for each release; at worst, it will encourage users to write new
migrations against an older version than they're using.

The other option would be to leave these bare, without any version
specifier. But as that's just a variant spelling of "4.2", it would seem
to raise the same concerns as above.

[ci-skip]

Moves the definition of an association to the top of the page. I am just starting to learn Rails, and having this definition at the top instead of in the second section would be really useful.

Updates the Types of Associations section for clarity. Moves the list of associations before the explanation.

Links to wikipedia articles on Primary and Foreign keys.

* #uniq is an alias of #distinct
* #uniq will be deprecated, see: rails/rails@adfab2dcf4003ca564d78d4425566dd2d9cd8b4f

* A `has_many` dependant association accepts `[:destroy, :delete_all, :nullify,
:restrict_with_error, :restrict_with_exception]` as options.
Currently the documentation references `delete` instead of `delete_all`
* Adds documentation for other options

The option was deprecated in 6eae366d

[Robin Dupret & Shunsuke Aida]

Improve the guide about `has_many` `collection.clear` to indicate
the behavior for each dependent strategy according to
`collection.delete_all`.

Based on #17179, I changed the `collection.delete` docs to also
clarify the default strategy for each `hm` and `hm:t` associations.

Fixes #20170.

The quoted underscore is being intepreted as markdown, causing the
entire phrase to be italicized.

Related to f1af967e. [ci skip]

Thanks for patch @sgrif :trollface:

Closes #18216

In the AR Associations Guide, this PR fixes:

- The counter_cache declaration is now shown only in the `belongs_to`
association.

- The docs stated that the counter_cache declaration needs to be on the
`has_many` side; now corrected to the `belongs_to` side.

- Split the custom column explanation out to a separate paragraph.

- Simplify the NOTE because it is true both with and without a custom
column name.

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