On 2015-12-16 23:32, H. S. Teoh via Digitalmars-d wrote:
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.
How would Ddoc know that you want to document the function and not the
template? Just assume so if there's only one symbol in the template? It
still needs to be possible to individually document the template and the
function, and least when there's more than one symbol in the template.
--
/Jacob Carlborg
