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

          Issue ID: 24697
           Summary: Function overload resolution is vague and incomplete
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: dlang.org
          Assignee: nobody@puremagic.com
          Reporter: qs.il.paperinik@gmail.com

Relevant section: https://dlang.org/spec/function.html#function-overloading

- It is unclear what is meant by implicit conversions and if all implicit
conversions are equal.
- It is unclear what is meant by a qualifier conversion (does it include lvalue
to rvalue conversion? What about @safe to @system conversion?)
- It is even unclear what exactly an exact match is (again, is lvalue to rvalue
conversion an exact match)
- It is unclear what “(including any this reference)” means exactly.
- It is not stated if function attributes (on the called function) affect
overload resolution

- “Literals do not match `ref` or `out` parameters.” Is not incorrect, but misleading. In general, rvalues are not literals, and it’s them who can’t bind to `ref` and `out`.

- “`scope` parameter storage class does not affect function overloading.” (Bad
grammar.) Okay, what about other parameter storage classes? There are `auto`
(for `auto ref`), `final` (can indeed be ignored), `in`, `lazy`, `out`, `ref`,
`return`, and `scope`, also user-defined ones. The effect of each of them
(except `final`) must be specified.

- The `-preview=rvaluerefparam` preview switch is not accounted for. - The `-preview=in` switch is not accounted for.

There are the following implicit conversions:
- integral conversion from a smaller-range type to a bigger one.
- derived class to base class/interface
- alias this
- lvalue to rvalue
- rvalue to lvalue (for `in` under preview)
- Weakening of attributes for function pointer and delegate types
- qualifier conversions

It may in fact be desirable to vet each of those individually and first judge then explain in the spec whether they fall into match level 2 or 3. E.g. it seems value category is considered by DMD akin to a qualifier, i.e. lvalue to rvalue conversion is not considered an implicit conversion.

Under the `in` preview, overload resolution is affected by whether the argument is bound by reference. IMO, matching against `in` should not depend on that.

Possibly, lvalue to rvalue conversion deserves its own matching level.

--