DDoc is an embarrassment

Paul Backus 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 [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

- 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 
ddoc comment

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

More information about the Digitalmars-d mailing list