Search code examples
phpdoc

PHPDoc usage for @since


The @since is used to show at what version a function was created. What if I later modify that function, should I change the @since value or do something else to show there was a change?


Solution

  • The basic use case for "@since" is indeed to only denote the package version when the method was first introduced.

    However, since this tag's contents is really just free form text, and I'm not aware of any documentation software using for special creation of any kind of other doc elements (e.g. a report of methods group by what version introduced them), then I really see no concern with using the tag in other ways.

    For example, change an original "@since 2.0 foo() introduced" to "@since 2.7 foo($arg)" to show that the API changed. I might even go so far as to use multiple tags, to show a history of the method's API:

    * @since 2.0 foo() introduced
    * @since 2.7 foo($arg) added the $arg argument to the signature
    * @since 2.9 foo($arg = 'default') set a default for $arg