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.
