Clarify and document operator overloading trait matching rules etc

[nikomatsakis]

Our current trait matching rules for operator overloading are somewhat ad-hoc. I've got a branch which implements a more straightforward set of rules, which I think is what we want for 1.0 going forward. Part of completing this bug will be updating the docs.

The rules I've in mind can be summarized as:

Given an expression l op r where op is a binary operator and l : L and r : R:

• We search for a trait impl Op<R,T> for L. Note that there is no attempt to autoderef l and so forth.
• At runtime we'll pass in &l and &r to the trait method (as is reflected in the &self type etc).
• The type of l op r is T.

[nikomatsakis]

Nominating for 1.0.

[pnkfelix]

Accepted for 1.0, P-backcompat-lang.

[nikomatsakis]

It occurs to me that if we make these changes we could avoid the need to know the type of x in x + 1. Basically we could just call it a plain trait match, and then add lang items for the built-in additions (x + 1 etc). Essentially all operators would be overloaded. The usual reason we haven't done this is that operations on ints and so forth are privileged in that they can appear in constant expressions. But there is no reason that we can't say that operations in constant expressions must resolve to lang items. It would also simplify a lot of other code if all operators were considered overloaded (up until trans, where I imagine we'd inline + and so forth rather than leaning on LLVM for that).

[nikomatsakis]

See #8280 for an example where this would help.

[flaper87]

visiting for triage. Nothing to add here

[alexcrichton]

Given https://github.com/rust-lang/rfcs/blob/master/text/0439-cmp-ops-reform.md and the fact that operators are no longer taking by reference, I believe this issue is resolved, so closing.