On Thursday, 7 June 2018 at 06:22:04 UTC, Mike Parker wrote:
@@@DEPRECATED_[version]@@@
This is still ambiguous to me. Deprecations are done in stages.
For example:
Stage 1 (version 2.081) - Compiler emits deprecation warning
Stage 2 (version 2.086 = 2.081 + 5) - Compiler emits error
Stage 3 (version 2.091 = 2.086 + 5) - Feature is removed.
In @@@DEPRECATED_[version]@@@ does "version" mean "2.081" or
"2.086". That is, is it the version in which the deprecation
happened (2.081), or is it the version for which the code must be
changed to an error (2.086). I believe it should be the former,
but I have been corrected in the past that it should be the
latter.
On the first release in the deprecation period, the removed
symbol(s) SHOULD be removed from any module or package wide
list of public functions/booktables/cheatsheets to deemphasize
its use.
I don't think that's a very good idea because users, in order to
transition their code, will need to refer to the existing
documentation in order to understand the semantics of their
existing code. I recommend, instead, requiring the documentation
to be annotated with a deprecation notice, and then removed when
the feature itself is removed.
I believe it would also make the document easier to read and
understand if the stages of deprecation were explicitly
documented as an ordered list with each list item having an
accompanying description. For example:
Stage 1 - Deprecation
Period - 5 releases (approximately 1 year)
Code is modified to emit a deprecation message.
Documentation is annotated with a deprecation message.
Stage 2 - Error
Period - 5 releases (approximately 1 year)
Code is modified to emit an error.
Documentation is modified to explain that the feature will result
in an error.
Stage 3 - Removal
Period - Indefinite
Code is removed.
Documentation is removed.
There may be cases here where the error must remain and the spec
updated to explain that the idiom results in an error. For
example: https://github.com/dlang/DIPs/pull/99
Mike
