version(StdDoc)

[H. S. Teoh]

On Sat, Nov 24, 2018 at 02:09:22AM +0000, Neia Neutuladh via Digitalmars-d-learn wrote:
> On Fri, 23 Nov 2018 17:21:25 -0800, H. S. Teoh wrote:
> > Ddoc may have its stink points, but in this case, the stuff inside
> > version(Windows) blocks simply isn't compiled, so you can't expect
> > ddoc to do much about it.  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 means that, instead of one site showing my project's
> documentation, I need a separate site for every combination of
> platform and version flags.  And users who care about differences
> between platforms and version flags need to manually cross-reference
> docs for every symbol and overload.
> 
> It's a pretty terrible status quo.

True.  I've tried to tackle this before, but conceded defeat after I
realized that dmd just can't handle it because of the way ddoc is
implemented.

Adam does have a very good point about showing all alternatives to docs,
though.  Arguably, that's what ddoc *should* do.  If the programmer
wrote a ddoc comment in the code, it probably should be processed as
part of doc generation, regardless of whether that code sits in some
deeply-nested version blocks that ends up not being compiled.  Binding
ddoc generation to the compile process seems not such a good idea in
retrospect.

Now that I think about this more carefully, I feel tempted to say that
we should write a standalone ddoc generator, or at least a standalone
module in dmd, that process *all* source code regardless of version
blocks and static ifs and what-not. The output should be properly tagged
(e.g., the path of version identifiers / static if conditions that lead
to a particular version of the doc) so that the formatting backend can
render it sensibly, e.g., as a HTML drop-down list of versions, or
whatever.

But then that would be reinventing what Adam has already done, right?
:-D


T

-- 
If I were two-faced, would I be wearing this one? -- Abraham Lincoln