This reverts commit 3420a145, reversing
changes made to afb66a5a.

This patch brings back the functionality of passing true to the
association proxy. The behavior was deprecated with #20888 and scheduled
for removal in Rails 5.1.

The deprecation mentioned that instead of `Article.category(true)` one
should use `article#reload.category`. Unfortunately the alternative does
not expose the same behavior as passing true to the reader
did. Specifically reloading the parent record throws unsaved changes and
other caches away. Passing true only affected the association.

This is problematic and there is no easy workaround. I propose to bring
back the old functionality by introducing this new reader method for
singular associations.

`:foreign_type` is a valid option for `belongs_to` and `has_one`
so remove this to `SingularAssociation`.

This class is only used internally. We should keep it out of public
documentation. This patch adds nodoc for
`ActiveRecord::Associations::Builder` and everything nested within.

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

Fixes #18696.

This option is unused, left over from pre-1.0 Rails to internally distinguish the location of the foreign key.

In addition to defining the association, a `required` association will
also have its presence validated.

Before:

```ruby
belongs_to :account
validates_presence_of :account
```

After:

```ruby
belongs_to :account, required: true
```

This helps to draw a distinction between types of validations, since
validations on associations are generally for data integrity purposes,
and aren't usually set through form inputs.

This is to get activerecord-deprecated_finders work again

It is need in activerecord-deprecated_finders

Previously, the `has_one` macro incorrectly accepts the `counter_cache` option
due to a bug, although that options was never supported nor functional on
`has_one` and `has_one ... through` relationships. It now correctly raises an
`ArgumentError` when passed that option.

For reference, this bug was introduced in 52f8e4b9.

the instance

of using +inverse_of: false+ option. Changing the documentation and
adding a CHANGELOG entry for the automatic inverse detection feature.

Added some more documentation for define_readers and define_writer of the Association and its inherited classes

the results. Added tests to check to make sure that inverse associations are
automatically found when has_many, has_one, or belongs_to associations
are defined.

Method compilation provides better performance and I think the code
comes out cleaner as well.

A knock on effect is that methods that get redefined produce warnings. I
think this is a good thing. I had to deal with a bunch of warnings
coming from our tests, though.

Well, not all of them, but some of them.

I don't think there's much reason for these methods to be private.

This change uses Module.redefine_method as defined in ActiveSupport.
Making Module.define_method public would be as clean in the code, and
would also emit warnings when redefining an association. That is pretty
messy given current tests, so I'm leaving it for someone else to decide
what approach is better.

Instead of generating association methods directly in the model
class, they are generated in an anonymous module which
is then included in the model class. There is one such module
for each association. The only subtlety is that the
generated_attributes_methods module (from ActiveModel) must
be forced to be included before association methods are created
so that attribute methods will not shadow association methods.

Use proper objects to do the work to build the associations (adding methods, callbacks etc) rather than calling a whole bunch of methods with rather long names.