Bug 18998 – Improve Operator Overloading docs

The language Operator Overloading document has devolved into chaos! Picture that you don't know D, and you want to learn about operator overloading, and now read that document. Press Ctrl-F and type "opSlice", scroll the highlighted text, try and understand how to implement a slicing operator properly. Note that the first contact you see looks like this: `-a[i..j] a.opIndexUnary!("-")(a.opSlice(i, j))` wat?! I think this document needs a complete overhaul, starting with a list of special operators that exist, description of each special operator and example of how they work in **the most simple case**, and show complex compounds and aggregate rewrites towards the end, only after the basic meaning of all operators has been established. This is a critical language document, and it's not terribly helpful to new users.

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.

Convenience link: https://dlang.org/spec/operatoroverloading.html

> Press Ctrl-F and type "opSlice", scroll the highlighted text, try and understand how to implement a slicing operator properly. Note that the first contact you see looks like this: `-a[i..j] a.opIndexUnary!("-")(a.opSlice(i, j))` wat?! Tweaked unary operator docs so there's now a brief explanation and link to slice overloading above the lowering table for opIndexUnary: https://github.com/dlang/dlang.org/pull/3463

This one adds examples for opCmp, opOpAssign, s.opIndex(s.opSlice(...)). https://github.com/dlang/dlang.org/pull/3467

> try and understand how to implement a slicing operator properly. Note that the first contact you see looks like this: > `-a[i..j] a.opIndexUnary!("-")(a.opSlice(i, j))` wat?! I think the docs for opIndexUnary, opIndexAssign and opIndexOpAssign should be moved to the Indexing and Slicing Operators section where they make more sense. > Make a point that multi-dimensional indexing is even supported, and that it is a separate topic, With the 2nd pull I have tweaked the slicing docs to introduce 1D slicing first with an example, then move on to multidimensional. > and requires different handling than 1d. Well non-template opSlice(i, j) 'is discouraged', so they're not different really.

@ntrel updated dlang/dlang.org pull request #3652 "[spec] Improve opCast & `opCast!bool` docs" mentioning this issue: - Part of Issue 18998 - Improve Operator Overloading docs https://github.com/dlang/dlang.org/pull/3652

dlang/dlang.org pull request #3652 "[spec] Improve opCast & `opCast!bool` docs" was merged into master: - a6cfd0db7b7f74ec27c2d908d017d82e5355023b by Nick Treleaven: Part of Issue 18998 - Improve Operator Overloading docs https://github.com/dlang/dlang.org/pull/3652

THIS ISSUE HAS BEEN MOVED TO GITHUB https://github.com/dlang/dlang.org/issues/4089 DO NOT COMMENT HERE ANYMORE, NOBODY WILL SEE IT, THIS ISSUE HAS BEEN MOVED TO GITHUB