I don't want to turn this thread into a DDoc-bashing rag, but
another observation I've made is that, ironicaly, DDoc macros are
not self documenting. If one types $(SOME_MACRO this, that, the
other) it's not immediately obvious to what 'this,' 'that,' 'the
other' refer without interpreting the macro definitions. Perhaps
this was a design feature in order to transfer the formatting
burden onto the .ddoc file, but I'm finding the exact opposite as
I look through the DLangSpec.
In contrast, <some-tag attr1="this" attr2="that">the
other</some-tag> is far more obvious in terms of what
relationship the variables have to one another. Again, I'm not
suggesting for a second that XML is the documenter's cure-all,
but illustrating some of the things which make DDoc macros
awkward to use.
What are the general opinions on La(Tex) in terms of code
documentation? I only have a superficial understanding of it but
it seems to follow many of the principles that DDoc incorporates.
It also has the advantage that it's not quite as obtrusive as XML
when writing from scratch. Then again, I read on Wikipedia that
Knuth's next incarnation of Tex is going to be XML-based. XML
seems to be the unavoidable trend in file design.
