search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
361 stars 85 forks source link

RFC: [PSR-5] @deprecated syntax could be better #138

Closed photodude closed 5 years ago

photodude commented 7 years ago

The proposed PSR-5 @deprecated syntax could be better. The current syntax suggests using a single-colon for separating the 'starting version' (version in which the associated element has been deprecated) and the 'ending version' (the version in which the associated element is scheduled for removal) Examples from current PSR-5

/**
   * @deprecated 1.0.0:2.0.0
   *
   * @deprecated :2.0.0
   */

In my opinion, this single-colon notation is too easy to misread and too easy for people to at a glance misunderstand. I would prefer some other character notation that has more visual significance for separating the 'starting version' from the 'ending version'

I suggest that hyphen notation for a single line @deprecated, is an improvement over the single-colon notation. Examples using hyphen notation

/**
   * @deprecated 1.0.0-2.0.0
   *
   * @deprecated -2.0.0
   */

I'm open to other options, that like hyphen notation, have more visual significance than the current proposed single-colon notation.

rob006 commented 7 years ago

Hyphen could be a part of a version, like 2.0.0-beta1.

photodude commented 7 years ago

@rob006 That is definitely true, "Hyphen could be a part of a version, like 2.0.0-beta1". It's unfortunate that Semantic Versioning even allows a Hyphen as part of the pre-release version scheme. I personally prefer 2.0.0.beta.1 to the Hyphenated pre-release version scheme.

But that's not the primary point I'm trying to bring up. It's that the single-colon notation doesn't hold enough visual weight when reading to prevent misreading it. Choosing a new character could/would improve general reading.

Here is a non-exhaustive list of other options; I'm open to any options that have more visual significance than the current proposed single-colon notation.

Alternative Char(s) example1 example2
Double colon :: @deprecated 1.0.0::2.0.0 @deprecated ::2.0.0
Forward slash / @deprecated 1.0.0/2.0.0 @deprecated /2.0.0
Double Forward slash // @deprecated 1.0.0//2.0.0 @deprecated //2.0.0
Backslash \ @deprecated 1.0.0\2.0.0 @deprecated \2.0.0
Double Backslash \\ @deprecated 1.0.0\\2.0.0 @deprecated \\2.0.0
Pointer -> @deprecated 1.0.0->2.0.0 @deprecated ->2.0.0
Tilde ~ @deprecated 1.0.0~2.0.0 @deprecated ~2.0.0
Hyphen - @deprecated 1.0.0-2.0.0 @deprecated -2.0.0
Underscore _ @deprecated 1.0.0_2.0.0 @deprecated _2.0.0
verbose words since #.#.# for removal in #.#.# @deprecated since 1.0.0 for removal in 2.0.0 @deprecated for removal in 2.0.0
ashnazg commented 5 years ago

Seems like this idea for a version range was itself a new idea when PSR-5 was being formulated, so it's possible that the usage isn't really out there in the wild yet. I'd be fine with considering another character if so.

Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions.

jaapio commented 5 years ago

I don't see why you would like to add this feature to this tag at all. This tag is an annotation to specify that a certain element will be removed in the future. It is unclear to me what the intention of the version in the deprecated tag means. Is it the version that will remove an element? Why would you standardize something that can be part of de original tag? It is up to the user what to write in the description.

GaryJones commented 5 years ago

The default "ending version" would presumably be the next major version, if using semver, so it seems this extra syntax would only be useful if either the project didn't follow semver, or they were deprecating something several major releases in advance. Other projects may deprecate, but never remove.

sun commented 5 years ago

Out of all options presented above, the single colon still looks most natural and most compatible.

Double colon could be an accepted alternative? We can allow both a single colon or a double colon?

ashnazg commented 5 years ago

My preference would be to drop the notion of the ending version altogether. Will wait for additional comments from working group and contributors.

neuro159 commented 5 years ago

What is expected workflow for these? Who and when actually looks at whats affected?

eg. I plan to update/just updated a dependency - run batch inspection for deprecation it before/after? (replace batch inspection with CI/Linter check if its your case)

ashnazg commented 5 years ago

@photodude , if you wish to pursue this further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig