Fix Issue 20015 - [REG 2.086] Deprecated -preview, -revert, and -transition options not documented

[RazvanN7]

No description provided.

[dlang-bot]

Thanks for your pull request and interest in making D better, @RazvanN7! We are looking forward to reviewing it, and you should be hearing from a maintainer soon.
Please verify that your PR follows this checklist:

• My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
• My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
• I have provided a detailed rationale explaining my changes
• New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

---

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

Bugzilla references

Auto-close	Bugzilla	Severity	Description
✓	20015	regression	[REG 2.086] Deprecated -preview, -revert, and -transition options not documented

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub run digger -- build "stable + dmd#13784"

[RazvanN7]

cc @ibuclaw

[Geod24]

Test[s]?

[RazvanN7]

I didn't add any because, currently, all deprecated features have their documentation purged and the fix is obviously correct.

[RazvanN7]

Furthermore, I don't see any tests for cli switches in the fail compilation directory. I understand where you come from @Geod24 , but I think that in this situation we can just merge this as is.

[MoonlightSentinel]

See

• testhelp.d
• previewhelp.d
• transitionhelp.d
• reverthelp.d

Shouldn't some of these tests fail with this PR?

[Geod24]

I didn't add any because, currently, all deprecated features have their documentation purged and the fix is obviously correct.

Side note: The main point of test is not to ensure that things work today (although it's still a pretty important side of it), but to ensure that they will work tomorrow. This is especially important for regression, because we have evidence of something that used to work that doesn't anymore.

Furthermore, I don't see any tests for cli switches in the fail compilation directory.

https://github.com/dlang/dmd/blob/master/test/fail_compilation/reserved_version_switch.d
And obviously what @MoonlightSentinel linked, although those are in the "compilable" directory.

[RazvanN7]

@Geod24 At this point there is no deprecated switch with public documentation in dmd. There is a deprecated transition (complex) and a deprecated preview (intpromote) but both have their public documentation disabled. One thing I could do is to enable their documentation and list them as deprecated. If that is not acceptable, then I don't know how I could possibly test this without introducing a mock-up deprecation. What do you think?

[RazvanN7]

@Geod24 The -transiton=complex is deprecated but it is not listed in the documentation. To be able to test this I marked it as documented and deprecated. Is that ok? I don't really understand what the strategy is here; my expectation was that once a switch is deprecated it is also purged from the documentation to avoid new uses of it (that would require a single Feature field, not 2), but it seems that it is possible to have an undocumented switch which is not deprecated (like preview=markdown on the stable branch). This seems weird to me, but I am obviously missing context here.

[RazvanN7]

cc @MoonlightSentinel

[Geod24]

Yes, that test is enough IMO

[Geod24]

This seems weird to me, but I am obviously missing context here.

It's good that the default was enabled but the switch became a no-op (and not deprecated). That's what we did for -dip25 too. This way, early adopters still get the behavior they expect, without needing to version their code to remove an annoying deprecation at a specific version.