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
