DDoc is an embarrassment

[Paul Backus]

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 [1] syntax to ddoc [2] 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 [3], 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
   https://issues.dlang.org/show_bug.cgi?id=5335

- Ddoc ignores methods in static else block
   https://issues.dlang.org/show_bug.cgi?id=11337

- Missing doc-comment for alias this, this(this)
   https://issues.dlang.org/show_bug.cgi?id=13069

- ddoc generator does not insert ddoc-ed unittest blocks for 
fromISOString, fromISOExtString, and fromSimpleString into the 
documentation
   https://issues.dlang.org/show_bug.cgi?id=16992

- Struct members missing from docs when the struct has a ditto 
ddoc comment
   https://issues.dlang.org/show_bug.cgi?id=18074

- Destructors and postblit constructors do not appear in DDoc 
output
   https://issues.dlang.org/show_bug.cgi?id=18860

- DDoc doesn't document symbols inside static foreach loops
   https://issues.dlang.org/show_bug.cgi?id=21399

- DDoc skips version else blocks inside templates
   https://issues.dlang.org/show_bug.cgi?id=21400

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.) [4]

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*.

[1] https://code.dlang.org/packages/adrdox
[2] https://dlang.org/spec/ddoc.html
[3] 
https://issues.dlang.org/buglist.cgi?keywords=ddoc&list_id=233822&resolution=---
[4] 
https://github.com/rejectedsoftware/ddox/issues?q=is%3Aissue+is%3Aopen+label%3A%22external+bug%22