On Wed, Dec 16, 2015 at 10:00:50PM +0000, Meta via Digitalmars-d wrote: > On Wednesday, 16 December 2015 at 21:57:05 UTC, Walter Bright wrote: [...] > >There's plenty to be done to improve things that converting all the > >pages to another format will not help with.
While I'm on the fence about the value of ddoc as a website programming language (not as a documentation generator, where it is excellent IMO), I'm doubtful of the value of converting wholesale to a different format at this present time. That's a lot of effort and drain of our scant resources, with only unverifiable claims of increased participation from nebulous crowds who so far haven't showed any signs of interest in participating yet. It's something we could perhaps consider in the long term, but right now there are far more important things we need to work on. Like actually improving what docs are currently there. > 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. T -- Valentine's Day: an occasion for florists to reach into the wallets of nominal lovers in dire need of being reminded to profess their hypothetical love for their long-forgotten.