-preview switches

[Steven Schveighoffer]

On 4/2/20 2:36 AM, Jacob Carlborg wrote:
> On 2020-04-01 19:51, Steven Schveighoffer wrote:
> 
>> 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.
> 
> That was me. Do you suggest that the Ddoc comments are moved to the 
> actual definitions and set the `Darwin` version identifier when 
> `CoreDdoc` is enabled? That might have been better, in this case.

Maybe. The problem with the current situation is that on MacOS those 
definitions are actually used elsewhere, but CoreDdoc trumps setting the 
Darwin version, so you get the wrong types defined here.

The duplicated symbols seems prone to error (you may add a symbol to the 
bottom, but not to the ddoc part). Just that problem alone seems like it 
would be worth being able to get this compiling without duplicating 
everything.

> It's difficult to know how to deal with this the best way. Different 
> modules solve this in different way.s We don't seem to have a standard 
> way to deal with this. In this case it might have worked, because this 
> module doesn't have any dependencies on other modules. But in other 
> cases that might not be the case. You need to make sure those symbols in 
> the other modules are available when building the docs.

I think the standard way should be to alter symbols that are not 
cross-platform only when needed (i.e. functions that can't compile on 
other platforms) as:

/// Documentation
version(CorrectPlatform)
    void foo()
    { // implementation
    }
else version(CoreDdoc)
    void foo(); // stub

This way, things aren't spread far apart, and symbols that compile just 
fine on other platforms are not affected.

There will be some exceptions. For instance system-level enums that have 
different values on different platforms. That's just going to be a hard 
module to maintain.

-Steve