API documentation tag @since

[sandio]

The @since tag indicates at which version did the associated Structural Elements became available. http://www.phpdoc.org/docs/latest/references/phpdoc/tags/since.html

We might want to use this when upgrading the API minor version x.Y.z. For example, this documentation tag is used by https://github.com/wp-cli/wp-cli

[pnikolov]

So this affects only minor version updates?

[sandio]

The idea is to put a @since tag in the documentation of a new function that adds new functionality to the API. When there is new functionality without breaking changes, the developer increments the minor version of the API. But when I think about it, the @since tag is also appropriate for new functionality that does introduce breaking changes, so it is applicable for major versions as well.

[pnikolov]

OK, this makes sense. I think we should adopt this approach for now on.