On 4/1/20 1:54 PM, Steven Schveighoffer wrote:
> On 4/1/20 1:12 PM, David Gileadi wrote:
>> Yes, it's that last thing--I'm exclusively on a Mac.
> 
> Well in that case, let's just see what happens ;)
> 
> https://github.com/dlang/druntime/pull/3016
> 

In almost all cases, it makes things better. Most of the examples of the differences are places where people were writing markdown not realizing it wouldn't come out that way in the ddocs.

Just a couple of quirks, I'll fix those and then we can merge this.

http://dtest.dlang.io/results/a3c49490a7db6ebcb0f84e9d4ef1613a0a6fcc80/53bd6f5ac68d43913111d8acbc620cc55574a1b3/

-Steve

On Wednesday, 1 April 2020 at 14:26:15 UTC, Atila Neves wrote:
>
> I think the right way to nudge D programmers to transition to where we can turn -preview into -revert is to issue deprecation messages for a while. Nothing like a noisy build to get people to file issues on github (or even better, PRs) to get this fixed.

Please note that deprecation messages are effectively errors in a build environment with -de (i.e. Weka). In that case the only workable compilation is to use the new way (i.e. with preview switch). Especially due to deprecation/error messages in speculative code, this can be annoying to deal with.
What is nice about _not_ showing deprecation messages and instead having only -preview, is that it is easier to switch to a new compiler (which always creates a ton of work already). And then slowly one can enable the preview options to get ready for the future. I do think that putting a date on certain things will help create some urgency to start future proofing code.

-Johan

On 4/1/20 3:01 PM, Johan wrote:
> On Wednesday, 1 April 2020 at 14:26:15 UTC, Atila Neves wrote:
>>
>> I think the right way to nudge D programmers to transition to where we can turn -preview into -revert is to issue deprecation messages for a while. Nothing like a noisy build to get people to file issues on github (or even better, PRs) to get this fixed.
> 
> Please note that deprecation messages are effectively errors in a build environment with -de (i.e. Weka). In that case the only workable compilation is to use the new way (i.e. with preview switch). Especially due to deprecation/error messages in speculative code, this can be annoying to deal with.
> What is nice about _not_ showing deprecation messages and instead having only -preview, is that it is easier to switch to a new compiler (which always creates a ton of work already). And then slowly one can enable the preview options to get ready for the future. I do think that putting a date on certain things will help create some urgency to start future proofing code.

I think compiler deprecation messages can be designated as not becoming errors for -de.

For example, I'm pretty sure the import changes that were done not too long ago had deprecation messages that never resulted in errors.

-Steve

On 2020-04-01 21:15, Steven Schveighoffer wrote:

> I think compiler deprecation messages can be designated as not becoming errors for -de.

Not sure I follow. The whole point of the `-de` flag is to turn deprecation messages into errors. By default, they're not errors.

-- 
/Jacob Carlborg

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.

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.

-- 
/Jacob Carlborg

On Thursday, April 2, 2020 12:30:49 AM MDT Jacob Carlborg via Digitalmars-d wrote:
> On 2020-04-01 21:15, Steven Schveighoffer wrote:
> > I think compiler deprecation messages can be designated as not becoming errors for -de.
>
> Not sure I follow. The whole point of the `-de` flag is to turn deprecation messages into errors. By default, they're not errors.

For compiler changes which have involved deprecated features or behavior, for better or worse, the messages haven't necessarily been affected by the compiler flags related to deprecation, whereas because deprecations in druntime or Phobos have actually used the deprecated keyword, they've been affected by the deprecation flags.

- Jonathan M Davis

On 4/1/2020 7:15 AM, Steven Schveighoffer wrote:
>    =dip25            implement 

#dip25 has been around for 4 years now. It's time to deprecate the old behaviors. We can start with that one.

On Wednesday, 1 April 2020 at 14:26:15 UTC, Atila Neves wrote:
> Walter and I discussed this last week.
>
> I think the right way to nudge D programmers to transition to where we can turn -preview into -revert is to issue deprecation messages for a while. Nothing like a noisy build to get people to file issues on github (or even better, PRs) to get this fixed.
>
> I expect the annoying messages to happen soon. Then we have to decide on how long of a period is appropriate to start break builds.

So basically warning messages? Does that mean this issue will finally be fixed? https://issues.dlang.org/show_bug.cgi?id=259


#issue259

On 4/1/20 2:57 PM, Steven Schveighoffer wrote:
> On 4/1/20 1:54 PM, Steven Schveighoffer wrote:
>> On 4/1/20 1:12 PM, David Gileadi wrote:
>>> Yes, it's that last thing--I'm exclusively on a Mac.
>>
>> Well in that case, let's just see what happens ;)
>>
>> https://github.com/dlang/druntime/pull/3016
>>
> 
> In almost all cases, it makes things better. Most of the examples of the differences are places where people were writing markdown not realizing it wouldn't come out that way in the ddocs.
> 
> Just a couple of quirks, I'll fix those and then we can merge this.

It's merged. Anyone want to make it the default?

There were 6 modules that were different with this change. In 4 of them, the documentation looked better, as the authors of the docs were expecting markdown-like behavior without realizing it wouldn't happen.

In one case, it appears that markdown interpreted a >= as the start of a blockquote (started with >).

In one case, someone used underscores for marking D code instead of dashes. This subtle problem looks very similar to the right thing when reviewing the source, but looks wrong on the actual docs (just underscores come out, and all the D code is just mashed together as plain text). The markdown turned these into <hr>, which actually looked a bit better, but drew attention to the fact that the wrong marking was used (the D code was still mashed up and not highlighted).

I think there is very little breakage that would happen from making this the default, and the worst thing that happens is your docs look funky until you fix them, or you find __ bugs ;)

BTW, thanks to Vladimir for the auto-tester for documentation, this made the process super-simple to see what happened, especially with the diff mode.

-Steve

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