Some feedback on the website.

[H. S. Teoh via Digitalmars-d]

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.