• d-bugmail puremagic.com (102/102) May 14 2021 https://issues.dlang.org/show_bug.cgi?id=21921

d-bugmail puremagic.com writes:

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

          Issue ID: 21921
           Summary: DDOC: Using only the first function in templates with
                    multiple functions
           Product: D
           Version: D2
          Hardware: x86
                OS: Windows
            Status: NEW
          Severity: trivial
          Priority: P1
         Component: dmd
          Assignee: nobody puremagic.com
          Reporter: john.michael.hall gmail.com

DDOC doesn't handle the case where you have multiple functions within a single
template. It will do a better job when some of the functions are also
templates. You get similar behavior with multiple outer templates.

The examples below are compiled with dmd -main -D filename.

1) Contrast the documentation of this one


```d
/++
Foo
+/
template foo(T, U)
    if (is(T : int) && !is(U : int))
{
    ///
    void foo(V)(T x, U y, V z) {}
    ///
    void foo(U x, T y) {}
}
```

with this one. The one above looks fine, exactly as you would expect. The one
below merges the first one with the outer level and then doesn't show the inner
level at all. 

```d
/++
Foo
+/
template foo(T, U)
    if (is(T : int) && !is(U : int))
{
    ///
    void foo(T x, U y) {}
    ///
    void foo(U x, T y) {}
}
```

2) This example looks at the case of multiple outer templates. Contrast this
with the one below

```d
/++
Foo
+/
template foo(T, U)
    if (is(T : int) && !is(U : int))
{
    ///
    void foo(V)(T x, U y, V z) {}
    ///
    void foo(U x, T y) {}
}

/// ditto
template foo(T)
    if (is(T : int))
{
    ///
    void foo(T x, T y)  {}
    ///
    void foo(T x)  {}
}
```

The one above shows the same information as what is in 1) above but also adds
the merged second definition of foo. The one below only shows the top level
merged ones. 

```d
/++
Foo
+/
template foo(T, U)
    if (is(T : int) && !is(U : int))
{
    ///
    void foo(T x, U y) {}
    ///
    void foo(U x, T y) {}
}

/// ditto
template foo(T)
    if (is(T : int))
{
    ///
    void foo(T x, T y)  {}
    ///
    void foo(T x)  {}
}
```

Here is a practical example:
https://github.com/libmir/mir-algorithm/blob/0965ada3d13b4be831875b0b754be9e7ae81999b/source/mir/math/stat.d#L339

Here are the associated docs:


--