DDoc is an embarrassment
snarwin at gmail.com
Mon Nov 16 22:04:17 UTC 2020
Recently, I've been working on submitting a dub package of mine,
sumtype, for inclusion in Phobos, D's standard library. Part of
this process was converting sumtype's documentation comments from
adrdox  syntax to ddoc  syntax.
However, when I ran ddoc on my updated module, I discovered
something strange: some of the symbols that were supposed to show
up in the documentation were missing. I hopped on over to
issues.dlang.org to see if there were any relevant bug reports,
and as I read through the search results , the awful truth
began to dawn on me:
DDoc doesn't work.
I don't mean "its output is ugly," or "it lacks useful features,"
or "the macro syntax is awkward"--I mean that in a frankly
staggering number of cases, DDoc flat-out fails to actually
generate documentation for code with documentation comments. You
know, the *one thing* it's supposed to do.
Here are some examples from bugzilla:
- DDoc ignores documentation comment that begins on the same line
as the open curly brace
- Ddoc ignores methods in static else block
- Missing doc-comment for alias this, this(this)
- ddoc generator does not insert ddoc-ed unittest blocks for
fromISOString, fromISOExtString, and fromSimpleString into the
- Struct members missing from docs when the struct has a ditto
- Destructors and postblit constructors do not appear in DDoc
- DDoc doesn't document symbols inside static foreach loops
- DDoc skips version else blocks inside templates
We ship this tool to every user of the D language. We advertise
it as one of the quality-of-life features that helps D stand out
from the crowd. And it doesn't work.
(And before you ask: no, ddox isn't any better.) 
Can someone explain to me why we haven't migrated everything to
adrdox yet? I mean, say whatever you want about the look & feel,
but at least it *actually generates documentation*.
More information about the Digitalmars-d