CODEWITHSUNDEEP
phpphpdoccomments
urok93
urok93

Reputation: 549

Use of @since in PHP code

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?

Upvotes: 14

Views: 4670

Answers (3)

josh3736
josh3736

Reputation: 145162

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.

Upvotes: 24

internals-in
internals-in

Reputation: 5048

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)
 {
     <...>
 }

Upvotes: 5

user1645055
user1645055

Reputation:

since is a phpDoc tag

PHPDoc tags work with some editors to display more information about a piece of code. It is useful to developers using those editors to understand what the purpose and where they would use it in their code.

The convention for allowing PHPdoc blocks is to have @since information (even if not available at the time) and @package information, which should always be "WordPress" unless it is an external library. like following

/**
 * ... Description(s) here
 *
 * @package WordPress
 * @since 2.1 or {@internal Unknown}}
 *
 * ... More information if needed.
 */

Please read following articles for more information on phpDoc tags

PHPDocumentor 0.4.1

Document when (at which version) an element was first added to a package

phpDocumentor Tutorial

phpDocumentor tags - How to use tags in DocBlocks

@since - phpDocumentor

Upvotes: 0

Related Questions