On 12/29/2014 4:37 PM, Kiith-Sa wrote:
If you're not using custom macros, and you find Ddoc tedious and repetitive,
you're using it wrong.
I cannot use a custom macro to shorten $(D a == b). A well-written paragraph
will have 20 such $(D XXX), $(B XXX), $(I XXX), not to mention $(SOMELINK
xxx.com XXX).
As opposed to some other markup language. You're always going to have 20 such
markup instances, one way or another.
And there's no way to make lists or tables readable:
Yes, there is. I just showed you.
Yes, *you* use DDoc all the time. But *you* are also forcing it on everyone
using the language, and on any average programmer who may potentially use D,
most of whom don't share your love for macros and MANY of whom know much more
common formats like Markdown. Most people don't write their docs in LaTeX
either.
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'm writing my *thesis* in ReStructuredText, which is basically Markdown on
steroids with *way* more special characters than Markdown, and I almost never
need to escape anything.
The D language has a use for most every character, so escapes will be needed a
lot.
to be usable, documentation must be as simple to generate as:
doxygen Doxyfile
dmd -D source.d
(And you don't have to go find a doxygen that works on your system, is
compatible with D source code, and is installed correctly.)
BTW, you can use Doxygen with D if you want to.
In fact, some people used Doxygen with D before D had Ddoc. If that actually
worked out well, Ddoc would never have been created. But it did not work out
well. It was a disaster. Few wanted to be bothered with installing Doxygen, so
what happened was little to no documentation got written. The Phobos docs often
bore no resemblance whatsoever to what the code did.
Ddoc revolutionized all that. It's hard to understate how desirable it is to
have it built in to the compiler, meaning everyone has it, and has the correct
version of it.
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 :-)
