Add a DEPRECATED macro for a consistent style of deprecation messages

[wilzbach]

Motivation:

• deprecation messages are currently inconsistent and ugly

https://dlang.org/phobos-prerelease/std_functional.html#.binaryReverseArgs https://dlang.org/phobos/std_traits.html#.isConvertibleToString https://dlang.org/phobos/std_c_stdlib.html https://dlang.org/phobos/std_datetime.html#.AutoStart https://dlang.org/phobos/std_datetime_stopwatch.html https://dlang.org/phobos/std_exception.html#.enforceEx

• this also makes it a lot easier to grep for deprecated symbols that are still visible in the docs (removing them is often forgotten / done a few months later)

Preview:

Mobile:

In Ddoc:

$(DEPRECATED 2.088, reverseBinaryArgs,
    Use $(REF reverseArgs, std,functional) instead.
)

CC @JackStouffer @jmdavis

See also: https://github.com/dlang/DIPs/pull/108

[dlang-bot]

Thanks for your pull request, @wilzbach!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[jmdavis]

Do we really need something so loud? What's wrong with the red text that we've been using for ages now? It's already arguably pretty obnoxious, and this is far worse.

[CyberShadow]

Red background is too much. Maybe red border + text?

[jmdavis]

I suppose a related question that maybe should affect the DIP on deprecations is which release should be listed in the documentation. The way that I've normally handled it is to say that the symbol would be removed in the release that it's removed from the documentation, which makes it easy to figure out when it should be removed from the documentation but has sometimes had the downside of confusing folks about how long the deprecation cycle is. So, maybe we should just be listing when it will be removed from Phobos and then remove it from the documentation the appropriate number of releases ahead of that release. If we have a standard number of releases for the deprecation cycle as proposed in the DIP, then counting back should then be easy enough.

[wilzbach]

FWIW I was inspired by this from the NodeJs documentation:

https://nodejs.org/api/assert.html#assert_legacy_mode

Red background is too much. Maybe red border + text?

Like this?

What's wrong with the red text that we've been using for ages now?

Hard to read (it's completely in red) + easier to grep + plus consistent "experience".

I suppose a related question that maybe should affect the DIP on deprecations is which release should be listed in the documentation.

That's an excellent question (!) and should definitely be defined by the DIP.

[CyberShadow]

Yes, that looks much better. Could you post a larger screenshot with how it looks in the context of the surrounding definitions?

[wilzbach]

(I also pushed a temporary commit, s.t. it can be previewed on DAutoTest)

[CyberShadow]

Looks like there are some uses in Druntime that need to be fixed first:

[CyberShadow]

I think a good way to quantify this is that the warning should catch your eye when you're reading the symbol's definition, but not be loud enough that it distracts you while you're scrolling through the symbol list. With that in mind I think it's still too loud, what do you think?