On Wednesday, 16 December 2015 at 21:17:43 UTC, deadalnix wrote:
> On Wednesday, 16 December 2015 at 20:59:46 UTC, JohnCK wrote:
>> On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
>>> I'm not so sure...
>>
>> Like they say: "A father will never agree that his child is ugly!"
>>
>> :)
>>
>> John.
>
> Please don't go there...

Dude just read my message above. Furthermore It was just a joke with Walter.

JohnCK.

On Wed, Dec 16, 2015 at 12:54:35PM -0800, Walter Bright via Digitalmars-d wrote: [...]
> I do agree that the macros defined in the site's .ddoc files are ridiculously overlapping, redundant, etc. That all could use a redesign and an overhaul, but that isn't Ddoc's fault. It's just like any piece of crap code that has suffered from too many quick&dirty hacks layered on to it.

I think you hit the nail on the head. The current dlang.org macros are a gigantic, inconsistent mess. I think some serious refactoring is in order here.


T

-- 
MACINTOSH: Most Applications Crash, If Not, The Operating System Hangs

On Wed, Dec 16, 2015 at 01:00:19PM -0800, Walter Bright via Digitalmars-d wrote:
> On 12/16/2015 12:21 AM, ZombineDev wrote:
> >Well DDoc may have it's disadvantages, but I'm certain that the documentation would have been far worse if it wasn't for it.
> 
> No need to speculate :-) Before Ddoc, the Phobos documentation was horrific, probably the worst I'd ever seen. It was so bad it was unusual for there to be any correct documentation for a particular function, or even anything at all.
> 
> Ddoc utterly transformed that, almost overnight. It's hard to underestimate the positive impact Ddoc has had on D documentation.

I don't think anybody is questioning the value of ddoc as a *documentation generator*. The issue here is whether it has the same value as a *website programming language*. Very different things.


T

-- 
"640K ought to be enough" -- Bill G. (allegedly), 1984. "The Internet is not a primary goal for PC usage" -- Bill G., 1995. "Linux has no impact on Microsoft's strategy" -- Bill G., 1999.

On Wednesday, 16 December 2015 at 21:30:32 UTC, H. S. Teoh wrote:
> I don't think anybody is questioning the value of ddoc as a *documentation generator*. The issue here is whether it has the same value as a *website programming language*. Very different things.

That I agree!

JohnCK.

On 12/16/2015 7:32 AM, Jack Stouffer wrote:
> 3. "Who wants to spend hours and hours of work writing a DDoc to Markdown
> converter or manually convert all existing pages? Do we have any volunteers?"

I can't even get consistent documentation of the parameters to a function:

For example:

    http://dlang.org/phobos/std_parallelism.html#.Task

What are 'fun' and 'Args' supposed to be? No example(s).

    http://dlang.org/phobos/std_functional.html

Not a single appearance of 'Params:' or 'Returns:. Inconsistent use of 'Example:' and 'Examples:'. Many missing examples. Etc.

There's plenty to be done to improve things that converting all the pages to another format will not help with.

On Wednesday, 16 December 2015 at 21:57:05 UTC, Walter Bright wrote:
> On 12/16/2015 7:32 AM, Jack Stouffer wrote:
>> 3. "Who wants to spend hours and hours of work writing a DDoc to Markdown
>> converter or manually convert all existing pages? Do we have any volunteers?"
>
> I can't even get consistent documentation of the parameters to a function:
>
> For example:
>
>     http://dlang.org/phobos/std_parallelism.html#.Task
>
> What are 'fun' and 'Args' supposed to be? No example(s).
>
>     http://dlang.org/phobos/std_functional.html
>
> Not a single appearance of 'Params:' or 'Returns:. Inconsistent use of 'Example:' and 'Examples:'. Many missing examples. Etc.
>
> There's plenty to be done to improve things that converting all the pages to another format will not help with.

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

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.

On 12/16/2015 2:32 PM, H. S. Teoh via Digitalmars-d wrote:
> 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.

Exactly.

We'll never get anywhere chasing people who say "I'll help only if you convert to my way of doing things." I've done enough of that in the past, and concluded they're just seeing how long you'll dance to their tune and have no real intention of ever helping - there will just be another excuse.

On 12/16/2015 12:59 PM, JohnCK wrote:
> On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
>> I'm not so sure...
>
> Like they say: "A father will never agree that his child is ugly!"
>
> :)

I've pontificated before about design mistakes in D that I've made. I also think that a lot of the dmd code I wrote is ugly crap.

On Wed, Dec 16, 2015 at 03:04:51PM -0800, Walter Bright via Digitalmars-d wrote:
> On 12/16/2015 12:59 PM, JohnCK wrote:
> >On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote:
> >>I'm not so sure...
> >
> >Like they say: "A father will never agree that his child is ugly!"
> >
> >:)
> 
> I've pontificated before about design mistakes in D that I've made. I also think that a lot of the dmd code I wrote is ugly crap.

It would be interesting to hear what you think are design mistakes.

And also, perhaps for the longer term, how you'd have done things differently if you could turn back time. :-)


T

-- 
Questions are the beginning of intelligence, but the fear of God is the beginning of wisdom.