-preview switches

[Steven Schveighoffer]

On 4/1/20 1:31 PM, Mathias LANG wrote:
> On Wednesday, 1 April 2020 at 17:12:00 UTC, David Gileadi wrote:
>>
>> Yes, it's that last thing--I'm exclusively on a Mac. I guess I could 
>> set up a VM in VirtualBox or something but so far I've been too 
>> lazy/distracted to make the time for it.
> 
> The way the documentation generator works at the moment is less than 
> ideal. If doesn't really take into account `static if`, `version`, 
> etc... The solution needs to be at the DMD level, not at the project level.

I don't know how to fix this. Basically, if you don't want to build the 
whole project as it is on each platform, you need to have special ddoc 
versions for things. In this case, you have enum definitions that are 
not defined on the platform that D builds its docs. So whoever did this 
replicated the entire file but just without any actual definitions, and 
tagged them for ddoc. I think this was the wrong approach, we should 
have tagged them and included the real definitions if version(CoreDdoc) 
was true.

I've seen a few "workarounds" for generating documentable code for 
multiple platforms, or for projects that include other libraries but 
don't want to build those other libraries just for ddoc.

An example of the latter is mysql-native, which defines stubs for vibe-d 
items for documentation, since vibe-d is optional.

I wonder if the way to build the documentation is simply to build it 
with all possible platform definitions, and section them off. The html 
could have a platform selector or something that allows you to see what 
your platform or configuration supports.

Something like a switch to dmd like:

-ddoc-config=OSX -ddoc-config=Linux ddoc-config=Linux,Have_Vibed

And then it generates all the docs for all those configurations based on 
trying each of those versions on the AST.

-Steve