[Issue 23946] New: specifications state that "there can only be destructor" which can be confusinf because of mixin templates

[d-bugmail at puremagic.com]

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

          Issue ID: 23946
           Summary: specifications state that "there can only be
                    destructor" which can be confusinf because of mixin
                    templates
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: b2.temp at gmx.com

§2 of https://dlang.org/spec/class.html#destructors states that "There can be
only one destructor per class, the destructor does not have any parameters, and
has no attributes. It is always virtual."

However this creates confusion as mixin templates are allowed to introduce a
destructor.

eg.

```
import std;

mixin template AddNewDtor()
{
    ~this()
    {
        writeln("Mixin dtor");
    }
}

class Foo
{
    ~this()
    {
        writeln("Class dtor");
    }

    mixin AddNewDtor;
}

void main()
{
    {
        auto s = scoped!Foo;

        // prints `Mixin dtor`
        // prints `Class dtor`
    }
}
```

The specifications should be more clear. While some might know that there are
the internal __dtor and __xdtor functions, the specs should mention that

"destructors introduced by mixin templates are implicitly called by the main
destructor and does not represent a real destructor" in
https://dlang.org/spec/template-mixin.html. 

That's just a suggestion, any other solution that would prevent a possible
confusion for new comers is welcome.

See NG thread :
https://forum.dlang.org/post/czoaymnhawdtishtckfk@forum.dlang.org

--