phpDocumentor/fig-standards — pull request #50 by sun (2014-05-18 17:53:55+00:00)
Title: Change meaning of @deprecated version + add scheduled-for-removal version

As [discussed](https://github.com/php-fig/fig-standards/pull/169#discussion-diff-12411155) on php-fig/fig-standards#169:

The meaning of the specified machine-readable version should be the version in which the code has been marked as deprecated. _(cf. `@since`)_

The current interpretation of the specified version is not compatible for larger (FOSS) projects that rely on volunteers to clean up obsolete legacy code. Realistically, such projects can only state the version in which a resource has been deprecated, but they cannot reliably state when exactly a contributor will remove it.

→ Deprecated code may exist for much longer than originally assumed/scheduled.

Usually, the version in which a resource is _scheduled for removal_ is mentioned in the description. Unfortunately, the description is (1) custom, (2) often unnecessarily wordy, and (3) can be parsed by humans only.

There are legitimate use-cases for both versions, and ideally, it should be possible to specify both versions in a _machine-readable_ way:

1. the version it _was_ deprecated in
2. the version in which it is _scheduled for removal_

```
@deprecated 2.0.0 3.0.0
```
→ This 99% use-case no longer needs a description. _(give or take a `@see`)_

In addition, the specified values are machine-readable by design. This means that documentation parsers (including IDEs) can automatically produce listings of elements that have been deprecated in version X (typical user question), or elements that should be removed in version Y (typical maintainer task).

The more data is machine-readable, the more information can be derived. Just the above answers would significantly help maintainers as well as users of larger FOSS projects.

Suggested synopsis:
```
@deprecated [<"Semantic Version"> [<"Semantic Version">]] []
```

1. Maintainers who want to specify the version in which a resource is scheduled for removal are always able to specify the version in which it has been marked as deprecated.
1. Maintainers who are unable to state the version in which a resource is scheduled for removal are still able to state the version since which it is deprecated.
1. Maintainers who don't care for versions at all can omit both versions.

Specifying the version in which a resource has been deprecated is actually very common practice, so I additionally replaced _MAY_ with _RECOMMENDED_.