[Issue 20553] New: Request to improve documentation of how alias declaration and alias parameter work with function overload sets

[d-bugmail at puremagic.com]

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

          Issue ID: 20553
           Summary: Request to improve documentation of how alias
                    declaration and alias parameter work with function
                    overload sets
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: dmd
          Assignee: nobody at puremagic.com
          Reporter: neuranuz at gmail.com

There are currently unclear by language documentation how the language works
when trying to get `alias` or pass `alias` template parameter when dealing with
function overload sets.
https://dlang.org/spec/template.html#alias-template
https://dlang.org/spec/declaration.html#alias

The question can be illustrated by simple example below:

void foo(string aaa) {}
void foo(string aaa, int bb) {}

template Bar(alias Func)
{
    //...
}

alias MyBar = Bar!foo;

After just reading documentation it's hard to reason what do I actuall pass to
Bar template in this example. Do I pass just the first overload of foo to bar?
Or do I pass the last one? Or do I pass entire overload set?

The same is for `plain` aliases:
alias myFoo = foo;
What is `myFoo` actually? I cannot say it for sure after reading docs.

Also this misundersanding could be when using some of the other language
constructs with overloads. For instance `typeof`:
https://dlang.org/spec/declaration.html#Typeof
And maybe there a other cases that I couldn't figure out yet.

It's pretty like the `gray zone` of the language. I can't get straight answer
without testing it at practice.

--