Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

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.