version(StdDoc)

[Adam D. Ruppe]

On Saturday, 24 November 2018 at 01:21:25 UTC, H. S. Teoh wrote:
> Ddoc may have its stink points, but in this case, the stuff 
> inside version(Windows) blocks simply isn't compiled

That is why I call it "poorly designed" and a major reason why I 
dropped it entirely and created my own doc generator from scratch 
(well, using libdparse, so not exactly scratch, but zero use of 
dmd's code).

> You can't just arbitrarily ddoc everything inside version 
> blocks, because then you'll end up with ddocs for stuff inside 
> version(none) and/or conflicting docs for alternative 
> declarations in, say, OS-specific version blocks, or 
> user-defined static if's.

That is easy to handle, you just treat it like overloads and 
display the version info along with the rest of it if both are 
documented. My doc generator does this and it is very useful - 
you can show what are under special version specifiers, call out 
OS differences, and more.

And if there are conflicting docs, the user ought to be able to 
see that!