On Wednesday, 16 December 2015 at 22:32:25 UTC, H. S. Teoh wrote:
On Wed, Dec 16, 2015 at 10:00:50PM +0000, Meta via
Digitalmars-d wrote:
There's also weird stuff like this, with an outer template and
a documented inner template function.
http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
This is a limitation of ddoc that needs to be fixed.
Historically, template functions used to be written like this:
template amap(Args...)
{
auto amap(Args args) {
implementation();
}
}
Then a shorthand was introduced (the so-called "eponymous
template" syntax), such that the above incantation could be
abbreviated to:
auto amap(Args...)(Args args) {
implementation();
}
It would appear that ddoc came after eponymous templates became
the norm, so currently, ddoc only understands ddoc comments
attached to the latter syntax, while it fails to recognize that
the former syntax is actually equivalent. Several other
functions in Phobos suffer from the resulting formatting
disparity, IIRC map(), and maybe reduce(), and one or two
others. It's rare enough that we don't encounter it very often,
but the functions affected happen to be ones that are likely to
be frequently used, so we really ought to fix this limitation
in ddoc.
I think in this particular case it can only be done with a nested
template, because there are two variadic parameters.