Sent from my iPhone
> On 25 Apr 2024, at 16:26, Rowan Tommins [IMSoP] <imsop....@rwec.co.uk> wrote:
>
> On 24 April 2024 18:18:28 BST, Jorg Sowa <jorg.s...@gmail.com> wrote:
>> What about setting this parameter vaguely as the boolean we can pass?
>> ...
>> #[Deprecated(since: $packageVersion > 5.5)]
>> #[Deprecated(since: PHP_VERSION_ID > 80100)]
>> #[Deprecated(since: date("Y-m-d") > "2024-01-21")]
>
>
> Even if these expressions were legal, as far as I know, standard reflection
> doesn't give any access to the source code or AST of how the attribute was
> written, so this would just end up with a meaningless "$since = true", and
> some source code that might as well be a comment.
>
> To be honest, I'm not really sure what I'd do with the information in a
> "since" field even if it was there. If you were running PHP 7.4, what
> difference would it make to know that create_function was deprecated in 7.2,
> rather than in 7.1 or 7.3? The two relevant facts are when the suggested
> replacement was introduced (in case you need to support multiple versions);
> and what is the soonest that the deprecated feature will be removed. The
> second in particular is something I would like every deprecation message to
> include, rather than the vague "may be removed in a future version".
>
> I found this discussion of "since" in Rust's implementation, but don't find
> the arguments in favour particularly compelling:
> https://github.com/rust-lang/rfcs/pull/1270#issuecomment-138043714
>
>
> Of interest, that discussion also linked to a related feature in Java, which
> could perhaps be added to a list in the RFC alongside the Rust and JetBrains
> ones already mentioned: https://openjdk.org/jeps/277
>
> It's interesting to note, for instance, that both Java and Rust designers
> considered a specific "replacement" field, but decided that it was unlikely
> to be useful in practice. The Java proposal states this nicely:
>
>> In practice, there is never a drop-in replacement API for
>> any deprecated API; there are always tradeoffs and
>> design considerations, or choices to be made among
>> several possible replacements. All of these topics require
>> discussion and are thus better suited for textual
>> documentation.
>
> The JetBrains attribute *does* include a "replacement" argument, but it's
> heavily tied into a specific use case: it contains a template used for code
> transformation in the IDE. Both it and "since" are explicitly marked
> "applicable only for PhpStorm stubs".
>
> Regards,
> Rowan Tommins
> [IMSoP]
>
I think it's worth pointing out that phpdoc has had a @deprecated [version]
[description] attribute for a long time - since is, IMO a different name for
"version" and indicates the version that element was deprecated. If you're on
X.y and it says it was deprecated in X.w you know you don't need to worry about
it being removed until at least Y.a.
Also, phpdoc *also* has a separate @since attribute, which documents the
*introduction or modification* of an element.
I think suggestions of a "Since" attribute "beside" the deprecated attribute
defeat the purpose of it being an attribute, on top of being confusing when
compared to existing phpdoc attributes.
#[Deprecated, Since(1.9)] to me, means "currently deprecated; introduced (or
significantly changed) in 1.9"
To mean what you're suggesting it would need to be
#[Deprecated, Since(1.9, 'Deprecated in favour of foo...')] which is just
needless duplication.
For those who don't see the point of `since`, I think the obvious answer is:
documentation. Rather than needing a separate docblock to detail the
deprecation, it can be all in one, just as parameter types and return types
are. This reduces duplication, and reduces possibility of mismatched values.
If you wanted it to be clearer I'd suggest maybe rename "since" to "version",
but that's more to give a hint at intended use than anything.
