[Issue 18998] Improve Operator Overloading docs

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=18998

--- Comment #1 from Manu <turkeyman at gmail.com> ---
I also suggest, for each operator as it is introduced, demonstrate the
'canonical' signature; what is the 'most standard/correct' way to specify these
functions in their most simple cases.

Imagine you were writing a D equivalent of std::vector, nothing could be
simpler in terms of API spec.
Read the section "Array Indexing and Slicing Operators Overloading" from the
perspective you were writing std::vector...

What indexing type to use? size_t?
What about argument ref-ness? ref? byval? auto ref?
Argument const-ness?
What should assignment operators return? `void`? A reference to `this` like
C++?
How to correctly handle the operators that receive strings?
  constraint:     int opBinary(string op) if (op == "+") { ... }
  specialisation: int opBinary(string op : "+") { ... }
  static-if:      int opBinary(string op) { static if (op == "+") { ... } }
Each have subtly different semantics with respect to overload selection, error
messages, etc. Default choices should be suggested.

This information being clearly provided will ensure that development of D
container classes will follow the same set of guidelines.

It's worth noting, the document is almost obsessed with 2-d
slicing/indexing/op-assignment concepts.
Make a point that multi-dimensional indexing is even supported, and that it is
a separate topic, and requires different handling than 1d.
Users might not imagine that multi-dimensional indexing/slicing is possible on
first contact.

I suggest establishing all indexing/slicing operators with respect to their
typical 1-d cases, and then have a specific section at the end relating n-d (or
2-d in this case) indexing/slicing mechanics.

--