DDoc is an embarrassment

[Adam D. Ruppe]

On Monday, 16 November 2020 at 22:36:08 UTC, H. S. Teoh wrote:
> Yes, this is the problem with implementing the doc generator in 
> the compiler
>
> There is no easy fix, however.

adrdox doesn't suffer from this.

Though it as its bugs in static if and version presentation, it 
*usually* manages to do the obvious thing, for example:

http://dpldocs.info/experimental-docs/arsd.simpledisplay.OpenGlShader.html

Just show the condition with the declaration (as you can see I 
actually turn `version(x) {} else {}` into just `version(!x)` 
since i think it is easier for human consumption here). The user 
can figure it out (hopefully).

> What should the output be, for example, if the `/// ditto`'d 
> symbols are both aggregates?

http://dpldocs.info/experimental-docs/test2.foo.html

Not that hard, I didn't even consider this case specifically and 
it worked well enough!

What adrdox does is if it sees the ditto comment, it dittos the 
*comment*, not the output. So it acts like you copy/pasted the 
same comment text, but then reprocesses it for each decl 
separately.

Then, knowing it was ditto'd, it marks the two symbols as 
"related".

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

Funny how adrdox manages to keep up with these things, but ddoc - 
despite (or perhaps BECAUSE of) being integrated in dmd doesn't.