On Wednesday, 16 December 2015 at 02:01:02 UTC, deadalnix wrote:
On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei
Alexandrescu wrote:
It seems knowing ddoc is part of knowing D. -- Andrei
I just cargo cult something when I contribute to
phobos/druntime. One cannot know everything.
Also, ddoc always appeared to me like a big NIH syndrome.
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.
What I like about it:
+ Good defaults for sections
+ Params section is checked at compile-time and has nice syntax
+ Everything that is not builtin can be implemented as a macro.
+ Recently added feature that allows you to wrap code with ` `
like in markdown
What I don't like about it:
+ It relies too much on macros for some of the stuff that could
have been builtin
+ This makes reading the docs in the source code of some phobos
function harder, because you need to mentally expand the macros
+ The macro syntax probably should have been something like
${MACRO ...} because ( and ) are more often used symbols and
syntax should be optimized for them (so you don't have to escape
them).
In general I prefer markdown's syntax for things like lists,
links, tables, bold and italic text, because it is more easily
readable and writable by humans.
