Use of @since in PHP code

Question

I am using the @since comment in my PHP code. I have a question about its use though. Say I have a function that performs a particular task, and it's been implemented in version 1.0.

So I currently have @since 1.0.

Now I go ahead and change the function's name, although the code inside remains the same. Should it now say @since 3.0 (the current version) or remain @since 1.0?

Answer 1

The function name didn't exist in 1.0, therefore @since should be 3.0. It's irrelevant that a differently-named function provided the same functionality in an old version; you wouldn't be able to use the new name in the old version. The docs say:

Use @since to document revisions, as in "This function has been a part of this package since version 2.0"

The purpose of @since is to tell someone using your package that "since version x, a function named foo exists. If you go and change foo to bar in v3 but leave @since as v1, then your docs would incorrectly state that it's safe to call bar() in v1. In fact, there was no bar() in v1, and the call would throw an error.

You might also consider keeping a function stub with the old name (which just calls the real function), and marking it @deprecated.

Answer 2

The @since tag indicates at with which version did the associated Structural Elements became available.

Syntax

@since [version] [<description>]

The @since tag can be used to indicate since which version specific Structural Elements have become available.

This information can be used to generate a set of API Documentation where the consumer is informed which application version is necessary for a specific element.

The version MUST follow the same rules as the @version tag’s vector and MAY have a description to provide additional information.

This tag can occur multiple times within a PHPDoc. In that case, each occurrence is treated as an entry to a change log. It is RECOMMENDED that you also provide a description to each such tag.

Example

  /**
  * @since 1.0.1 First time this was introduced.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

 /**
  * @since 1.0.2 Added the $b argument.
  * @since 1.0.1 Added the $a argument.
  * @since 1.0.0
  *
  * @return void
  */
 function dump($a, $b)
 {
     <...>
 }