Worst Phobos documentation evar!

[jklp via Digitalmars-d]

On Monday, 29 December 2014 at 05:39:16 UTC, Walter Bright wrote:
> On 12/28/2014 8:44 AM, Kiith-Sa wrote:
>> It depends on the function being documented. For 'downcase', 
>> such blocks are
>> overkill;
>
> After doing it both ways for a while, I'm pretty convinced they 
> are not overkill even for trivial functions:
>
> 1. they lend an air of consistency and comfort to the reader
> 2. they provide an anchor for automated tools which can extract 
> the information
> 3. without such a block, I've found that I (and others, 
> http://dlang.org/phobos/std_algorithm.html#.sort) tend to omit 
> descriptions of 'obvious' parameters which are actually not 
> obvious at all.
> 4. a block can be styled in a custom manner
>
>
>> DDoc is powerful, but it is a very nasty case of "hard things 
>> are possible, easy
>> things are hard" (e.g. tables, and very unreadable in source 
>> $(B bold) instead
>> of **bold**, $(D code) instead of `code`, $(LINK2 ...), etc. .
>
> Having used both Ddoc and Markdown, I seriously disagree with 
> this. Take a look at the markdown source for DIP69. It's 
> horrific.
>
>
>> I think it'd be a good idea to add at least a subset of 
>> markdown to DMD DDoc,
>> which could generate DDoc macros (e.g. **bold**, *italic*, 
>> `inline code` (DDoc
>> already has nice syntax for code *blocks*), 
>> [link](www.link.com), and some table
>> syntax (not in vanilla markdown, but e.g. GitHub 
>> markdown/PanDoc markdown have a
>> common syntax)
>>
>> - I may be able to find some time to work on this for DMD DDoc 
>> in summer (not
>> sooner unfortunately, I'd need some time to look around the 
>> code as I never
>> touched it), but would it have a chance of being merged? 
>> (Walter?)
>
> I'd rather not accept some Markdown dialect into Ddoc.

I like your sense of the compromise. DDoc is mostly usefull to 
generate the doc as html but inside the sources, it's often 
**unreadable**. I think that you know that documentation comments 
as markdow would be good but maybe you're scared because of the 
consequences implied when rendering dlang.org std reference and 
such things.
And if both could live together ?

If I had the power to do this, DDoc would be primilarly 
'markdown' with optionally html and macros things allowed.