As opposed to some other markup language. You're always going
to have 20 such markup instances, one way or another.
There's a big difference between the amount of visual noise
between different instances. I'm using D for 5 years and when I
still find DDoc laced with $(LI $(B bold) $(D code)) hard to read.
And there's no way to make lists or tables readable:
Yes, there is. I just showed you.
I don't consider that to be readable, especially, as I mentioned,
if the items are long lines of non-plain text.
No matter what form Ddoc takes, it will force some method upon
users. However, you can use Doxygen on .d sources if you prefer.
I don't use it because it doesn't *really* understand D.
I'm not arguing for Doxygen's syntax / D support or lack thereof.
I'm arguing for its user experience.
The D language has a use for most every character, so escapes
will be needed a lot.
D blocks in DDoc are usually in:
---
code here
---
With a Markdown-like syntax, inline code could be in `inline
code here` .
I admit you would need to escape the backticks, which are very
rare,
especially in inline code fragments. I also admit *that* would
force you
to not reliably use *some* D code fragments *outside* backticks.
And I
find it unlikely that there are more than 3 fragments in entire
Phobos doc
this would break.
to be usable, documentation must be as simple to generate as:
doxygen Doxyfile
dmd -D source.d
The result takes a shitload of work to make it useful, especially
if
your project has more than 1 module (and no, passing more files
won't help
with that).
THIS is useful (it's very close to what Doxygen spits out by
default):
http://irrlicht.sourceforge.net/docu/index.html
D claims to have a builtin documentation generator, but you can
either spend a week searching for nonexistent documentation about
how to make decent documentation *or* you can get a third-party
documentation generator, which is the same experience you get
with C++ and Doxygen.
The only place anyone has to use Ddoc is in the Phobos
documentation. If Doxygen is better, more convenient, etc., why
aren't you using it? Ddoc must be doing something right :-)
I'm modifying a third-party documentation generator to support
Markdown and to get decent "Doxygen doxyfile" user experience
right now.
