std.exception: undocument enforceEx

[wilzbach]

Just saw this while reviewing #5233.
The docs for enforceEx explicitly say:

This is legacy name, it is recommended to use enforce!E instead.

While there has been some resistance against deprecations, a good step to help the reader and avoid confusion would be to undocument the symbol.

[JackStouffer]

I vote for deprecation first, then undocument

[quickfur]

I'd also say, deprecate first before undocumenting.

[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.

[wilzbach]

I'd also say, deprecate first before undocumenting.

@jmdavis I hope I have done it correctly this time - maybe you could put about an DEPRECATIONS.md in the root folder with exact guidelines? Would be awesome!

[wilzbach]

Hmm seems like enforce doesn't use eponymous templates and thus doesn't support partial instantiation:

std/format.d(1175): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/format.d(1258): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/format.d(1268): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/format.d(1878): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/format.d(2462): Error: template instance std.format.formatValue!(Appender!string, uint, char) error instantiating
std/conv.d(137):        instantiated from here: formatValue!(Appender!string, dchar, char)
std/conv.d(974):        instantiated from here: toStr!(string, dchar)
std/conv.d(201):        instantiated from here: toImpl!(string, dchar)
std/conv.d(4053):        ... (4 instantiations, -v to show) ...
std/format.d(1324):        instantiated from here: parse!(int, const(char)[])
std/bigint.d(869):        instantiated from here: FormatSpec!char
std/format.d(1326): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/conv.d(2168): Error: template instance std.conv.convError!(const(char)[], uint) error instantiating
std/format.d(1337):        instantiated from here: parse!(uint, const(char)[])
std/bigint.d(869):        instantiated from here: FormatSpec!char
std/format.d(1338): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (ulong, string)
std/format.d(1358): Error: template instance std.conv.parse!(ubyte, const(char)[]) error instantiating
std/bigint.d(869):        instantiated from here: FormatSpec!char
std/format.d(1361): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/format.d(1411): Error: function std.exception.enforce!(FormatException).enforce (FormatException value, lazy Throwable ex) is not callable using argument types (bool, string)
std/format.d(474): Error: template instance std.format.FormatSpec!char.FormatSpec.writeUpToNextSpec!(Appender!string) error instantiating
std/format.d(5766):        instantiated from here: formattedWrite!(Appender!string, char, ulong, ulong)
std/typecons.d(421):        instantiated from here: format!(char, ulong, ulong)
std/encoding.d(3520):        instantiated from here: Tuple!(BOM, "schema", ubyte[], "sequence")
std/conv.d(137): Error: template std.format.formatValue cannot deduce function from argument types !()(Appender!string, char, FormatSpec!char), candidates are:
``

Does anyone remember why `enforce` didn't use eponymous templates?

[MetaLang]

@wilzbach it probably predates that particular idiom. I think enforce is quite old.

[jmdavis]

@wilzbach it probably predates that particular idiom. I think enforce is quite old.

enforce is old enough that it was mentioned in TDPL as being in std.contracts. Breaking up a templated function so that it's first parameter is in a wrapper template is definitely a more recent practice then that, and AFAIK, even now, we generally only do it when someone decides they want to be able to partially instantiate a templated function for one reason or another.

@jmdavis I hope I have done it correctly this time - maybe you could put about an DEPRECATIONS.md

Well, if you're going to keep deprecating things, I guess that I'll have to do something like that. Normally, what I would do is put this at the top of enforceEx:

// @@@DEPRECATED_2018-07@@@
/++
    $(RED Deprecated. Please use $(LREF enforce) instead. This function will be removed
               in July 2018.)

and add this to enforceEx

deprecated("Please use enforce instead")

However, if enforce can't fully replace enforceEx, then it needs to stick around for at least one more release so that we can have a release where enforce can fully replace enforceEx. That way, someone can build their code with both the latest release and master without getting a bunch of deprecation messages. And clearly, from how enforceEx is being used in Phobos, enforce needs to be improved first. So, please create a PR to improve enforce, and then we can deprecate enforceEx after the improved enforce has been put out in a release.