DDoc is an embarrassment

H. S. Teoh hsteoh at quickfur.ath.cx
Mon Nov 16 22:36:08 UTC 2020


On Mon, Nov 16, 2020 at 10:04:17PM +0000, Paul Backus via Digitalmars-d wrote:
[...]
> DDoc doesn't work.
[...]
> - DDoc ignores documentation comment that begins on the same line as
> the open curly brace
>   https://issues.dlang.org/show_bug.cgi?id=5335

Wow, this one's been around for *that* long?!  Why isn't it fixed yet?


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

Yes, this is the problem with implementing the doc generator in the
compiler: the static else is elided by the time the ddoc code looks at
it, so it sees nothing and does nothing.

There is no easy fix, however. Potentially the static-if condition could
be false for a good reason -- e.g., the code is obsolete and should not
be documented. Or the static-if could be switching between two OSes / OS
versions, in which case you want to document *both* branches (but how do
you convey that in the generated docs?).


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

Yeah, this one is a bona fide bug.


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

This is another symptom of the way ddoc is implemented in the compiler:
it expects all overloads to be declared consecutively. Break that
assumption, and all sorts of weird things can happen.  It *should* be
fixed, but might potentially require building ddoc.d from ground up. :-P
(Not necessarily a bad thing, IMNSHO.)


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

The whole `/// ditto` thing is a hack, because there's an implicit
assumption that you only apply it to symbols of like kind (like two
functions, two structs, etc.).  When they're of two different kinds,
weird things happen, like here.  It would be fun to find out what
happens, for example, if you `/// ditto` together two completely
disparate symbols, like a struct and a class, or an alias and a struct,
etc..

What should the output be, for example, if the `/// ditto`'d symbols are
both aggregates?  How should their members be formatted in the output?
I don't think anybody even thought of this when ditto was implemented.


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

Ouch.  Yeah, ddoc is a completely separate subsystem in the compiler,
and I can see how when new features are added, the ddoc implications
would be neglected.


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

ditto. ;-)


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

I think it skips version else blocks in general. Probably the same bug
as #11337.


> 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]

Isn't ddox basically a better skin over ddoc? It follows the same
parsing flawed assumptions that vanilla ddoc has.


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

I second this.  Adrdox fixes a lot of the flaws in the current ddoc
implementation, and really should be the default rather than the current
flawed version of ddoc.  (But I'm also anticipating an uphill fight to
pry the ddoc macro system out of Walter's cold, dead, hands...)


T

-- 
He who does not appreciate the beauty of language is not worthy to bemoan its flaws.


More information about the Digitalmars-d mailing list