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.
