/docs/PSR.md
Markdown | 2006 lines | 1499 code | 507 blank | 0 comment | 0 complexity | e89569c20aa3b171d38d64b7684debdc MD5 | raw file
Possible License(s): LGPL-3.0
Large files files are truncated, but you can click here to view the full file
- PSR-n: PHPDoc
- =============
- Author(s):
- Mike van Riel (@mvriel) <mike.vanriel@naenius.com>
- Acknowledgements:
- The author(s) wish to thank Chuck Burgess (@ashnazg), Gary Jones (@GaryJ)
- and all other people who commented and contributed on various versions of
- this proposal.
- Obsoletes:
- [De-facto PHPDoc Standard][DEFACTO]
- ## Table Of Contents
- 1. Introduction
- 2. Conventions Used In This Document
- 3. Definitions
- 4. Basic Principles
- 5. The PHPDoc Format
- 5.1. Short Description
- 5.2. Long Description
- 5.3. Tags
- 5.3.1. Tag Name
- 5.3.2. Tag Signature
- 5.3.3. Inline PHPDoc
- 5.4. Examples
- 6. Inheritance
- 6.1. Class Or Interface
- 6.2. Function Or Method
- 6.3. Constant Or Property
- 7. Describing hashes
- 8. Describing anonymous functions
- 8. Tags
- 8.1. @api
- 8.2. @author
- 8.3. @category [deprecated]
- 8.4. @copyright
- 8.5. @deprecated
- 8.6. @example
- 8.7. @global
- 8.8. @internal
- 8.9. @license
- 8.10. @link
- 8.11. @method
- 8.12. @package
- 8.13. @param
- 8.14. @property
- 8.15. @return
- 8.16. @see
- 8.17. @since
- 8.18. @struct
- 8.19. @subpackage [deprecated]
- 8.20. @throws
- 8.21. @todo
- 8.22. @type
- 8.23. @uses
- 8.24. @var [deprecated]
- 8.25. @version
- Appendix A. Types
- Appendix B. Differences Compared With The De-facto PHPDoc Standard
- ## 1. Introduction
- The main purpose of this PSR is to provide a complete and formal definition of
- the PHPDoc standard. This PSR deviates from its predecessor, the de-facto PHPDoc
- Standard associated with [phpDocumentor 1.x][PHPDOC.ORG], to provide
- support for newer features in the PHP language and to address some of the
- shortcomings of its predecessor.
- This document SHALL NOT:
- * Describe a standard for implementing annotations via PHPDoc. Although it does
- offer versatility which makes it possible to create a subsequent PSR based on
- current practices. See [chapter 5.3](#53-tags) for more information on this
- topic.
- * Describe best practices or recommendations for Coding Standards on the
- application of the PHPDoc standard. This document is limited to a formal
- specification of syntax and intention.
- ## 2. Conventions Used In This Document
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
- interpreted as described in [RFC 2119][RFC2119].
- ## 3. Definitions
- * "PHPDoc" is a section of documentation which provides information on several
- aspects of a "Structural Element".
- > It is important to note that the PHPDoc and the DocBlock are two separate
- > entities. The DocBlock is the combination of a DocComment, which is a type
- > of comment, and a PHPDoc entity. It is the PHPDoc entity that contains the
- > syntax as described in chapter 5 such as the description and tags.
- * "Structural Element" is a collection of Programming Constructs which SHOULD be
- preceded by a DocBlock. The collection contains the following constructs:
- * namespace
- * require(_once)
- * include(_once)
- * class
- * interface
- * trait
- * function (including methods)
- * property
- * constant
- * variables, both local and global scope.
- It is RECOMMENDED to precede a "Structural Element" with a DocBlock with its
- definition and not with each usage.
- Example:
- ```php
- /** @type int $int This is a counter. */
- $int = 0;
- // there should be no docblock here
- $int++;
- ```
- or
- ```php
- /**
- * This class acts as an example on where to position a DocBlock.
- */
- class Foo
- {
- /** @type string|null $description Should contain a description */
- protected $description = null;
- /**
- * This method sets a description.
- *
- * @param string $description A text with a maximum of 80 characters.
- *
- * @return void
- */
- public function setDescription($description)
- {
- // there should be no docblock here
- $this->description = $description;
- }
- }
- ```
- An example of use that falls beyond the scope of this Standard is to document
- the variable in a foreach explicitly; several IDEs use this information to
- assist their auto-completion functionality.
- This Standard does not cover this specific instance as a `foreach` statement
- is not considered to be a "Structural Element" but a Control Flow statement.
- ```php
- /** @type \Sqlite3 $sqlite */
- foreach($connections as $sqlite) {
- // there should be no docblock here
- $sqlite->open('/my/database/path');
- <...>
- }
- ```
- * "DocComment" is a special type of comment which starts with `/**`, ends
- with `*/` and may contain any number of lines in between.
- When a DocComment spans multiple lines, every line SHOULD start with an
- asterisk that is aligned with the first asterisk of the opening clause.
- In case a DocComment spans multiple lines then every line should start with
- an asterisk (`*`) that is aligned with the first asterisk of the opening
- clause.
- Single line example:
- ```php
- /** <...> */
- ```
- Multiline example:
- ```php
- /**
- * <...>
- */
- ```
- * "DocBlock" is a "DocComment" containing a single "PHPDoc" structure and
- represents the basic in-source representation.
- * "Tag" is a single piece of meta information regarding a "Structural Element"
- or a component thereof.
- * "Inline PHPDoc" is a "PHPDoc" that is related to a "Tag" instead of a
- "Structural element". It replaces the description part of the "Tag".
- * "Type" is the determination of what type of data is associated with an element.
- This is commonly used when determining the exact values of arguments, constants,
- properties and more.
- See Appendix A for more detailed information about types.
- * "Semantic Version" refers to the definition as set in the [Semantic Versioning
- Specification 2.0.0][SEMVER2].
- * "FQSEN" is an abbreviation for Fully Qualified Structural Element Name. This
- notation expands on the Fully Qualified Class Name and adds a notation to
- identify class/interface/trait members and re-apply the principles of the FQCN
- to Interfaces, Traits, Functions and global Constants.
- The following notations can be used per type of "Structural Element":
- *Namespace*: `\My\Space`
- *Function*: `\My\Space\myFunction()`
- *Constant*: `\My\Space\MY_CONSTANT`
- *Class*: `\My\Space\MyClass`
- *Interface*: `\My\Space\MyInterface`
- *Trait*: `\My\Space\MyTrait`
- *Method*: `\My\Space\MyClass::myMethod()`
- *Property*: `\My\Space\MyClass::$my_property`
- *Class Constant*: `\My\Space\MyClass::MY_CONSTANT`
- * "FQSEN" is short for 'Fully Qualified Structural Element Name'. This is the
- unique identifier for each Structural Element and should not occur more than
- once in a project.
- A FQSEN has the following [ABNF][RFC5234]
- definition:
- FQSEN = fqnn / fqcn / constant / method / property / function
- fqnn = "\" [name] *("\" [name])
- fqcn = fqnn "\" name
- constant = (fqnn "\" / fqcn "::") name
- method = fqcn "::" name "()"
- property = fqcn "::$" name
- function = fqnn "\" name "()"
- name = (ALPHA / "_") *(ALPHA / DIGIT / "_")
- Example, namespace:
- `\My\Space`
- Example, function:
- `\My\Space\function()`
- Example, constant:
- `\My\Space\constant`
- Example, trait:
- `\My\Space\FactoryTrait`
- Example, interface:
- `\My\Space\FactoryInterface`
- Example, class:
- `\My\Space\Factory`
- Example, method:
- `\My\Space\Factory::method()`
- Example, class constant:
- `\My\Space\Factory::constant`
- ## 4. Basic Principles
- * A PHPDoc MUST always be contained in a "DocComment"; the combination of these
- two is called a "DocBlock".
- * A DocBlock MUST directly precede a "Structural Element"
- > An exception to this principle is the File-level DocBlock which MUST be
- > placed at the top of a PHP source code file.
- ## 5. The PHPDoc Format
- The PHPDoc format has the following [ABNF][RFC5234]
- definition:
- PHPDoc = [short-description] [long-description] [tags]
- inline-phpdoc = "{" *SP PHPDoc *SP "}"
- short-description = *CHAR ("." 1*CRLF / 2*CRLF)
- long-description = 1*(CHAR / inline-tag) 1*CRLF ; any amount of characters
- ; with inline tags inside
- tags = *(tag 1*CRLF)
- inline-tag = "{" tag "}"
- tag = "@" tag-name [tag-details]
- tag-name = (ALPHA / "\") *(ALPHA / DIGIT / "\" / "-" / "_")
- tag-details = *SP (SP tag-description / tag-signature / inline-phpdoc)
- tag-description = 1*CHAR
- tag-signature = "(" *tag-argument ")"
- tag-argument = *SP 1*CHAR [","] *SP
- Examples of use are included in chapter 5.4.
- ### 5.1. Short Description
- A short description MUST contain an abstract of the "Structural Element"
- defining the purpose. It is RECOMMENDED for short descriptions to span a single
- line or at most two but not more than that.
- A short description MUST end with either
- * a full stop (.) followed by a line break
- * or two sequential line breaks.
- If a long description is provided, then it MUST be preceded by a short
- description. Otherwise the long description will be considered the short
- description, until the stop of the short description is encountered.
- Tags do not have to be preceded by a short description but it is RECOMMENDED
- to do so.
- ### 5.2. Long Description
- The long description is OPTIONAL but SHOULD be included when the
- "Structural Element", which this DocBlock precedes, contains more operations, or
- more complex operations, than can be described in the short description alone.
- Any application parsing the long description is RECOMMENDED to support the
- Markdown mark-up language for this field so that it is possible for the author
- to provide formatting and a clear way of representing code examples.
- Common uses for the long description are (amongst others):
- * To provide more detail than the short description on what this method does.
- * To specify of what child elements an input or output array, or object, is
- composed.
- * To provide a set of common use cases or scenarios in which the
- "Structural Element" may be applied.
- ### 5.3. Tags
- Tags provide a way for authors to supply concise meta-data regarding the
- succeeding "Structural Element". They commonly consist of a name followed by
- white-space and a description or Inline PHPDoc.
- If a description is provided, it MAY span multiple lines and COULD follow a
- strict format dictated by the type of tag, as indicated by its name.
- The meta-data supplied by tags could result in a change of actual runtime behaviour
- of the succeeding "Structural Element", in which case the term "Annotation" is
- commonly used instead of "Tag".
- A variation of this is where, instead of a description, a tag-signature is used;
- in most cases the tag will in fact be an "Annotation". The tag-signature is
- able to provide the annotation with parameters regarding its operation.
- If a tag-signature is present then there MUST NOT be a description present in
- the same tag.
- Annotations will not be described in further detail in this specification as
- this falls beyond scope. This specification provides a basis on top of which
- annotations may be implemented.
- #### 5.3.1. Tag Name
- Tag names indicate what type of information is represented by this tag, or in
- case of annotations which behaviour must be injected into the succeeding
- "Structural Element".
- In support of annotations, it is allowable to introduce a set of tags designed
- specifically for an individual application or subset of applications (and thus
- not covered by this specification).
- These tags, or annotations, MUST provide a namespace by either
- * prefixing the tag name with a PHP-style namespace, or by
- * prefixing the tag name with a single vendor-name followed by a hyphen.
- Example of a tag name prefixed with a php-style namespace (the prefixing slash
- is OPTIONAL):
- ```php
- @\Doctrine\Orm\Mapping\Entity()
- ```
- > *Note*: The PHPDoc Standard DOES NOT make assumptions on the meaning of a tag
- > unless specified in this document or subsequent additions or extensions.
- >
- > This means that you CAN use namespace aliases as long as a prefixing namespace
- > element is provided. Thus the following is legal as well:
- >
- > @Mapping\Entity()
- >
- > Your own library or application may check for namespace aliases and make a
- > FQCN from this; this has no impact on this standard.
- > *Important*: Individual Documentation Generation Applications (DGAs) MAY
- > interpret namespaces that are registered with that application and apply
- > custom behaviour.
- Example of a tag name prefixed with a vendor name and hyphen:
- ```php
- @phpdoc-event transformer.transform.pre
- ```
- Tag names that are not prefixed with a vendor or namespace MUST be described in
- this specification (see chapter 7) and/or any official addendum.
- #### 5.3.2. Tag Signature
- Tag signatures are commonly used for annotations to supply additional meta-data
- specific to the current tag.
- The supplied meta-data can influence the behavior of the owning annotation and
- as such influence the behavior of the succeeding "Structural Element".
- The contents of a signature are to be determined by the tag type (as described
- in the tag-name) and fall beyond the scope of this specification. However, a
- tag-signature MUST NOT be followed by a description or other form of meta-data.
- #### 5.3.3. Inline PHPDoc
- Specific Tags MAY have an "Inline PHPDoc" section at the end of the "Tag"
- definition. An "Inline PHPDoc" is a "PHPDoc" element enclosed in braces and is
- only present at the end of a "Tag" sequence unless specified otherwise in a
- "Tag" definition, the "Inline PHPDoc" element MUST replace any description that
- COULD have been provided.
- An example can be the @method tag. This tag may be augmented using an
- "Inline PHPDoc" to provide additional information regarding the parameters,
- return value or any other tag supported by functions and methods.
- Chapter 5.4 contains an example of use for this construct.
- ### 5.4. Examples
- The following examples serve to illustrate the basic use of DocBlocks; it is
- advised to read through the list of tags in chapter 8.
- A complete example could look like the following example:
- ```php
- /**
- * This is a short description.
- *
- * This is a long description. It may span multiple lines
- * or contain 'code' examples using the _Markdown_ markup
- * language.
- *
- * @see Markdown
- *
- * @param int $parameter1 A parameter description.
- * @param \Exception $e Another parameter description.
- *
- * @\Doctrine\Orm\Mapper\Entity()
- *
- * @return string
- */
- function test($parameter1, $e)
- {
- ...
- }
- ```
- It is also allowed to omit the long description:
- ```php
- /**
- * This is a short description.
- *
- * @see Markdown
- *
- * @param int $parameter1 A parameter description.
- * @param \Exception $parameter2 Another parameter description.
- *
- * @\Doctrine\Orm\Mapper\Entity()
- *
- * @return string
- */
- function test($parameter1, $parameter2)
- {
- }
- ```
- Or even omit the tags section as well (though in the following example is not
- encouraged as you are missing information on the parameters and return value):
- ```php
- /**
- * This is a short description.
- */
- function test($parameter1, $parameter2)
- {
- }
- ```
- A DocBlock may also span a single line as shown in the following example.
- ```php
- /** @type \ArrayObject $array */
- public $array = null;
- ```
- Some tags may even feature an "Inline PHPDoc" as shown in the following example.
- ```php
- /**
- * @method integer MyMagicMethod(string $argument1) {
- * This is the short description for MyMagicMethod.
- *
- * @param string $argument1
- *
- * @return integer
- * }
- */
- class MyMagicClass
- {
- ...
- }
- ```
- ## 6. Inheritance
- PHPDoc's also have the ability to inherit information when the succeeding
- "Structural Element" has a super-element (such as a super-class or a method with
- the same name in a super-class or implemented in a super-interface).
- Every "Structural Element" MUST inherit the following PHPDoc parts by default:
- * [Short description](#51-short-description)
- * [Long description](#52-long-description)
- * A specific subset of [tags](#53-tags)
- * [@version](#724-version)
- * [@author](#72-author)
- * [@copyright](#74-copyright)
- Each specific "Structural Element" MUST also inherit a specialized subset as
- defined in the sub-chapters.
- The PHPDoc parts MUST NOT be inherited when a replacement is available in the
- sub-element. The exception to this rule is when the {@inheritdoc} inline tag is
- present in the long description. When present the parser MUST insert the
- super-element's long description at the location of the {@inheritdoc} inline
- tag, while still including the current element's description.
- Inheritance takes place from the root of a class hierarchy graph to its leafs.
- This means that anything inherited in the bottom of the tree MUST 'bubble' up to
- the top unless overridden.
- > Note: a special circumstance here would be when the Long Description must be
- > overridden but the Short Description should stay intact. It would be difficult
- > for a reader to distinguish which is overridden.
- >
- > In this case the writer MUST use the {@inheritdoc} inline tag as
- > Short Description and override the Long Description with the intended text.
- >
- > Without the {@inheritdoc} inline tag the reader MUST interpret any text
- > as if the Short Description would be overridden and long description MAY
- > appear overridden if the block of text contains a Short Description ending
- > as defined in the ABNF.
- ### 6.1. Class Or Interface
- In addition to the inherited descriptions and tags as defined in this chapter's
- root, a class or interface MUST inherit the following tags:
- * [@package](#712-package)
- A class or interface SHOULD inherit the following deprecated tags if supplied:
- * [@subpackage](#718-subpackage)
- The @subpackage MUST NOT be inherited if the @package annotation of the
- super-class (or interface) is not the same as the @package of the child class
- (or interface).
- Example:
- ```php
- /**
- * @package Framework
- * @subpackage Controllers
- */
- class Framework_ActionController
- {
- <...>
- }
- /**
- * @package My
- *
- class My_ActionController extends Framework_ActionController
- {
- <...>
- }
- ```
- In the example above the My_ActionController MUST NOT inherit the subpackage
- _Controllers_.
- ### 6.2. Function Or Method
- In addition to the inherited descriptions and tags as defined in this chapter's
- root, a function or method in a class or interface MUST inherit the following tags:
- * [@param](#713-param)
- * [@return](#715-return)
- * [@throws](#719-throws)
- ### 6.3. Constant Or Property
- In addition to the inherited descriptions and tags as defined in this chapter's
- root, a constant or property in a class MUST inherit the following tags:
- * [@type](#721-type)
- A constant or property SHOULD inherit the following deprecated tags if supplied:
- * [@var](#723-var)
- ## 7. Describing hashes
- The structure of a hash may be described using an "Inline PHPDoc" as part of a
- @type, @param or @return declaration or using the @struct tag in the Class'
- DocBlock.
- In either case each element of the hash is denoted with a @type declaration in
- the "Inline PHPDoc". Using this tag it is possible to indicate type, name and
- purpose of the element.
- Please note that the variable name part of the @type tag still needs to be
- preceded by a dollar sign for readability and parsability of the tag.
- Example:
- ```php
- /**
- * Initializes this class with the given options.
- *
- * @param string[] $options {
- * @type boolean $required Whether this element is required
- * @type string $label The display name for this element
- * }
- */
- public function __construct(array $options = array())
- {
- <...>
- }
- ```
- ### As @struct declaration
- In some cases a hash should be documented multiple times in the same class. For
- these purposes you COULD declare it as a 'virtual' "Structural Element" using
- the @struct tag in the declaration of a Class or Interface.
- It is RECOMMENDED to use native language constructs in these situations, such as
- a class.
- Please see the @struct documentation on how to use this tag.
- ## 8. Tags
- Unless specifically mentioned in the description each tag MAY occur zero or more
- times in each "DocBlock".
- ### 8.1. @api
- The @api tag is used to declare "Structural Elements" as being suitable for
- consumption by third parties.
- #### Syntax
- @api
- #### Description
- The @api tag represents those "Structural Elements" with a public visibility
- which are intended to be the public API components for a library or framework.
- Other "Structural Elements" with a public visibility serve to support the
- internal structure and are not recommended to be used by the consumer.
- The exact meaning of "Structural Elements" tagged with @api MAY differ per
- project. It is however RECOMMENDED that all tagged "Structural Elements" SHOULD
- NOT change after publication unless the new version is tagged as breaking
- Backwards Compatibility.
- #### Examples
- ```php
- /**
- * This method will not change until a major release.
- *
- * @api
- *
- * @return void
- */
- function showVersion()
- {
- <...>
- }
- ```
- ### 8.2. @author
- The @author tag is used to document the author of any "Structural Element".
- #### Syntax
- @author [name] [<email address>]
- #### Description
- The @author tag can be used to indicate who has created a "Structural Element"
- or has made significant modifications to it. This tag MAY also contain an
- e-mail address. If an e-mail address is provided it MUST follow
- the author's name and be contained in chevrons, or angle brackets, and MUST
- adhere to the syntax defined in RFC 2822.
- #### Examples
- ```php
- /**
- * @author My Name
- * @author My Name <my.name@example.com>
- */
- ```
- ### 8.3. @category [deprecated]
- The @category tag is used to organize groups of packages together but is
- deprecated in favour of occupying the top-level with the @package tag.
- As such, usage of this tag is NOT RECOMMENDED.
- #### Syntax
- @category [description]
- #### Description
- The @category tag was meant in the original de-facto Standard to group several
- @packages into one category. These categories could then be used to aid
- in the generation of API documentation.
- This was necessary since the @package tag as defined in the original Standard did
- not contain more then one hierarchy level; since this has changed this tag SHOULD
- NOT be used.
- Please see the documentation for `@package` for details of its usage.
- This tag MUST NOT occur more than once in a "DocBlock".
- #### Examples
- ```php
- /**
- * Page-Level DocBlock
- *
- * @category MyCategory
- * @package MyPackage
- */
- ```
- ### 8.4. @copyright
- The @copyright tag is used to document the copyright information of any
- "Structural element".
- #### Syntax
- @copyright <description>
- #### Description
- The @copyright tag defines who holds the copyright over the "Structural Element".
- The copyright indicated with this tag applies to the "Structural Element" to
- which it applies and all child elements unless otherwise noted.
- The format of the description if governed by the coding standard of each
- individual project. It is RECOMMENDED to mention the year or years which are
- covered by this copyright and the organization involved.
- #### Examples
- ```php
- /**
- * @copyright 1997-2005 The PHP Group
- */
- ```
- ### 8.5. @deprecated
- The @deprecated tag is used to indicate which 'Structural elements' are
- deprecated and are to be removed in a future version.
- #### Syntax
- @deprecated [<"Semantic Version">] [<description>]
- #### Description
- The @deprecated tag declares that the associated 'Structural elements' will
- be removed in a future version as it has become obsolete or its usage is
- otherwise not recommended.
- This tag MAY also contain a version number up till which it is guaranteed to be
- included in the software. Starting with the given version will the function be
- removed or may be removed without further notice.
- It is RECOMMENDED to provide an additional description stating why the
- associated element is deprecated.
- If it is superceded by another method it is RECOMMENDED to add a @see tag in the
- same 'PHPDoc' pointing to the new element.
- #### Examples
- ```php
- /**
- * @deprecated
- * @deprecated 1.0.0
- * @deprecated No longer used by internal code and not recommended.
- * @deprecated 1.0.0 No longer used by internal code and not recommended.
- */
- ```
- ### 8.6. @example
- The @example tag is used to link to an external source code file which contains
- an example of use for the current "Structural element". An inline variant exists
- with which code from an example file can be shown inline with the Long
- Description.
- #### Syntax
- @example [URI] [<description>]
- or inline:
- {@example [URI] [:<start>..<end>]}
- #### Description
- The example tag refers to a file containing example code demonstrating the
- purpose and use of the current "Structural element". Multiple example tags may
- be used per "Structural element" in case several scenarios are described.
- The URI provided with the example tag is resolved according to the following
- rules:
- 1. If a URI is proceeded by a scheme or root folder specifier such as `phar://`,
- `http://`, `/` or `C:\` then it is considered to be an absolute path.
- 2. If the URI is deemed relative and a location for the example files has been
- provided then the path relative to the given location is resolved.
- 3. If the previous path was not readable or the user has not provided a path
- then the application should try to search for a folder 'examples' in the
- same folder as the source file featuring the example tag. If found then an
- attempt to resolve the path by combining the relative path given in the
- example tag and the found folder should be made.
- 4. If the application was unable to resolve a path given the previous rules then
- it should check if a readable folder 'examples' is found in the root folder
- of the project containing the source file of the "Structural Element".
- > The root folder of a project is the highest folder common to all files
- > that are being processed by a consuming application.
- If a consumer intends to display the contents of the example file then it is
- RECOMMENDED to use a syntax highlighting solution to improve user experience.
- The rules as described above also apply to the inline tags. The inline tag
- has 2 additional parameters with which to limit which lines of code
- are shown in the Long Description. Due to this, consuming applications MUST
- show the example code in case an inline example tag is used.
- The start and end argument may be omitted but the ellipsis should remain in
- case either is used to give a clear visual indication. The same rules as
- specified with the [substr][PHP_SUBSTR] function of PHP are in effect with
- regards to the start and end limit.
- > A consuming application MAY choose to support the limit format as used in the
- > previous standard but it is deprecated per this PSR.
- > The previous syntax was: {@example [URI] [<start>] [<end>]} and did not support
- > the same rules as the substr function.
- #### Examples
- ```php
- /**
- * Counts the number of items.
- * {@example http://example.com/foo-inline.https:2..8}
- *
- * @example http://example.com/foo.phps
- *
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- ```
- ### 8.7. @global
- TODO: The definition of this item should be discussed and whether it may or
- may not be superceded in part or in whole by the @type tag.
- The @global tag is used to denote a global variable or its usage.
- #### Syntax
- @global ["Type"] [name]
- @global ["Type"] [description]
- #### Description
- Since there is no standard way to declare global variables, a @global tag MAY
- be used in a DocBlock preceding a global variable's definition. To support
- previous usages of @global, there is an alternate syntax that applies to
- DocBlocks preceding a function, used to document usage of global
- variables. In other words, there are two usages of @global: definition and
- usage.
- ##### Syntax for the Global's Definition
- Only one @global tag MAY be allowed per global variable DocBlock. A global
- variable DocBlock MUST be followed by the global variable's definition before
- any other element or DocBlock occurs.
- The name MUST be the exact name of the global variable as it is declared in
- the source.
- ##### Syntax for the Global's Usage
- The function/method @global syntax MAY be used to document usage of global
- variables in a function, and MUST NOT have a $ starting the third word. The
- "Type" will be ignored if a match is made between the declared global
- variable and a variable documented in the project.
- #### Examples
- (TODO: Examples for this tag should be added)
- ### 8.8. @internal
- The @internal tag is used to denote that the associated "Structural Element" is
- a structure internal to this application or library. It may also be used inside
- a long description to insert a piece of text that is only applicable for
- the developers of this software.
- #### Syntax
- @internal
- or inline:
- {@internal [description]}}
- The inline version of this tag may, contrary to other inline tags, contain
- text but also other inline tags. To increase readability and ease parsing
- the tag should be terminated with a double closing brace, instead of a single
- one.
- #### Description
- The @internal tag can be used as counterpart of the @api tag, indicating that
- the associated "Structural Element" is used purely for the internal workings of
- this piece of software.
- When generating documentation from PHPDoc comments it is RECOMMENDED to hide the
- associated element unless the user has explicitly indicated that internal elements
- should be included.
- An additional use of @internal is to add internal comments or additional
- description text inline to the Long Description. This may be done, for example,
- to withhold certain business-critical or confusing information when generating
- documentation from the source code of this piece of software.
- #### Examples
- Mark the count function as being internal to this project:
- ```php
- /**
- * @internal
- *
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- /**
- * Counts the number of Foo.
- *
- * {@internal Silently adds one extra Foo to compensate for lack of Foo }}
- *
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- ```
- ### 8.9. @license
- The @license tag is used to indicate which license is applicable for the
- associated 'Structural Elements'.
- #### Syntax
- @license [<url>] [name]
- #### Description
- The @license tag provides the user with the name and URL of the license that is
- applicable to 'Structural Elements' and any of their child elements.
- It is NOT RECOMMENDED to apply @license tags to any 'PHPDoc' other than
- file-level PHPDocs as this may cause confusion which license applies at which
- time.
- Whenever multiple licenses apply there MUST be one @license tag per applicable
- license.
- Instead of providing a URL an identifier as identified in the
- [SPDX Open Source License Registry][SPDX] MAY be provided
- and this SHOULD be interpreted as if having the URL mentioned in the registry.
- #### Examples
- ```php
- /**
- * @license MIT
- * @license http://www.spdx.org/licenses/MIT MIT License
- */
- ```
- ### 8.10. @link
- The @link tag indicates a custom relation between the associated
- "Structural Element" and a website, which is identified by an absolute URI.
- #### Syntax
- @link [URI] [description]
- or inline
- @link [URI] [description]
- #### Description
- The @link tag can be used to define a relation, or link, between the
- "Structural Element", or part of the long description when used inline,
- to an URI.
- The URI MUST be complete and welformed as specified in RFC 2396.
- The @link tag MAY have a description appended to indicate the type of relation
- defined by this occurrence.
- #### Examples
- ```php
- /**
- * @link http://example.com/my/bar Documentation of Foo.
- *
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- /**
- * This method counts the occurences of Foo.
- *
- * When no more Foo ({@link http://example.com/my/bar}) are given this
- * function will add one as there must always be one Foo.
- *
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- ```
- ### 8.11. @method
- The @method allows a class to know which 'magic' methods are callable.
- #### Syntax
- @method [return type] [name]([type] [parameter], [...]) [description]
- #### Description
- The @method tag is used in situation where a class contains the `__call()` magic
- method and defines some definite uses.
- An example of this is a child class whose parent has a `__call()` to have dynamic
- getters or setters for predefined properties. The child knows which getters and
- setters need to be present but relies on the parent class to use the `__call()`
- method to provide it. In this situation, the child class would have a @method
- tag for each magic setter or getter method.
- The @method tag allows the author to communicate the type of the arguments and
- return value by including those types in the signature.
- When the intended method does not have a return value then the return type MAY
- be omitted; in which case 'void' is implied.
- @method tags MUST NOT be used in a PHPDoc that is not associated with a
- *class* or *interface*.
- #### Examples
- ```php
- class Parent
- {
- public function __call()
- {
- <...>
- }
- }
- /**
- * @method string getString()
- * @method void setInteger(integer $integer)
- * @method setString(integer $integer)
- */
- class Child extends Parent
- {
- <...>
- }
- ```
- ### 8.12. @package
- The @package tag is used to categorize "Structural Elements" into logical
- subdivisions.
- #### Syntax
- @package [level 1]\[level 2]\[etc.]
- #### Description
- The @package tag can be used as a counterpart or supplement to Namespaces.
- Namespaces provide a functional subdivision of "Structural Elements" where the
- @package tag can provide a *logical* subdivision in which way the elements can
- be grouped with a different hierarchy.
- If, across the board, both logical and functional subdivisions are equal is
- it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.
- Each level in the logical hierarchy MUST separated with a backslash (`\`) to
- be familiar to Namespaces. A hierarchy MAY be of endless depth but it is
- RECOMMENDED to keep the depth at less or equal than six levels.
- Please note that the @package applies to different "Structural Elements"
- depending where it is defined.
- 1. If the @package is defined in the *file-level* DocBlock then it only applies
- to the following elements in the applicable file:
- * global functions
- * global constants
- * global variables
- * requires and includes
- 2. If the @package is defined in a *namespace-level* or *class-level* DocBlock
- then the package applies to that namespace, class or interface and their
- contained elements.
- This means that a function which is contained in a namespace with the
- @package tag assumes that package.
- This tag MUST NOT occur more than once in a "DocBlock".
- #### Examples
- ```php
- /**
- * @package PSR\Documentation\API
- */
- ```
- ### 8.13. @param
- The @param tag is used to document a single parameter of a function or method.
- #### Syntax
- @param ["Type"] [name] [<description>]
- #### Description
- With the @param tag it is possible to document the type and function of a
- single parameter of a function or method. When provided it MUST contain a
- "Type" to indicate what is expected; the description on the other hand is
- OPTIONAL yet RECOMMENDED. For complex structures such as option arrays it is
- RECOMMENDED to use an "Inline PHPDoc" to describe the option array.
- The @param tag MAY have a multi-line description and does not need explicit
- delimiting.
- It is RECOMMENDED when documenting to use this tag with every function and
- method. Exceptions to this recommendation are:
- This tag MUST NOT occur more than once per parameter in a "PHPDoc" and is
- limited to "Structural Elements" of type method or function.
- #### Examples
- ```php
- /**
- * Counts the number of items in the provided array.
- *
- * @param mixed[] $array Array structure to count the elements of.
- *
- * @return int Returns the number of elements.
- */
- function count(array $items)
- {
- <...>
- }
- ```
- The following example demonstrates the use of an "Inline PHPDoc" to document
- an option array with 2 elements: 'required' and 'label'.
- ```php
- /**
- * Initializes this class with the given options.
- *
- * @param string[] $options {
- * @type boolean $required Whether this element is required
- * @type string $label The display name for this element
- * }
- */
- public function __construct(array $options = array())
- {
- <...>
- }
- ```
- ### 8.14. @property
- The @property tag allows a class to know which 'magic' properties are present.
- #### Syntax
- @property ["Type"] [name] [<description>]
- #### Description
- The @property tag is used in the situation where a class contains the
- `__get()` and `__set()` magic methods and allows for specific names.
- An example of this is a child class whose parent has a `__get()`. The child
- knows which properties need to be present but relies on the parent class to use the
- `__get()` method to provide it.
- In this situation, the child class would have a @property tag for each magic
- property.
- @property tags MUST NOT be used in a "PHPDoc" that is not associated with
- a *class* or *interface*.
- #### Examples
- ```php
- class Parent
- {
- public function __get()
- {
- <...>
- }
- }
- /**
- * @property string $myProperty
- */
- class Child extends Parent
- {
- <...>
- }
- ```
- ### 8.15. @return
- The @return tag is used to document the return value of functions or methods.
- #### Syntax
- @return <"Type"> [description]
- #### Description
- With the @return tag it is possible to document the return type of a
- function or method. When provided, it MUST contain a "Type" (See Appendix A)
- to indicate what is returned; the description on the other hand is OPTIONAL yet
- RECOMMENDED in case of complicated return structures, such as associative arrays.
- The @return tag MAY have a multi-line description and does not need explicit
- delimiting.
- It is RECOMMENDED to use this tag with every function and method.
- Exceptions to this recommendation are:
- 1. **constructors**: the @return tag MAY be omitted here, in which case an
- interpreter MUST interpret this as if `@return self` is provided.
- 2. **functions and methods without a `return` value**: the @return tag MAY be
- omitted here, in which case an interpreter MUST interpret this as if
- `@return void` is provided.
- This tag MUST NOT occur more than once in a "DocBlock" and is limited to the
- "DocBlock" of a "Structural Element" of a method or function.
- #### Examples
- ```php
- /**
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- /**
- * @return string|null The label's text or null if none provided.
- */
- function getLabel()
- {
- <...>
- }
- ```
- ### 8.16. @see
- The @see tag indicates a reference from the associated "Structural Elements" to
- a website or other "Structural Elements".
- #### Syntax
- @see [URI | "FQSEN"] [<:type:>] [<description>]
- #### Description
- The @see tag can be used to define a reference to other
- "Structural Elements" or to an URI.
- When defining a reference to another "Structural Elements" you can refer to a
- specific element by appending a double colon and providing the name of that
- element (also called the "FQSEN").
- A URI MUST be complete and well-formed as specified in [RFC 2396][RFC2396].
- The type of reference MAY be provided after the URI or FQSEN by mentioning a
- string wrapped in colons that defines the type of relation.
- (TODO: where do we keep a list of recommended relation types? here? separate
- RFC (my preference) or somewhere on the internet?)
- The @see tag SHOULD have a description appended to provide additional
- information regarding the relationship between the 2 elements.
- #### Examples
- ```php
- /**
- * @see number_of() :alias:
- * @see MyClass::$items For the property whose items are counted.
- * @see MyClass::setItems() To set the items for this collection.
- * @see http://example.com/my/bar Documentation of Foo.
- *
- * @return integer Indicates the number of items.
- */
- function count()
- {
- <...>
- }
- ```
- ### 8.17. @since
- The @since tag is used to denote _when_ an element was introduced or modified,
- using some description of "versioning" to that element.
- #### Syntax
- @since [<"Semantic Version">] [<description>]
- #### Description
- Documents the "version" of the introduction or modification of any element.
- It is RECOMMENDED that the version matches a semantic version number (x.x.x)
- and MAY have a description to provide additional information.
- 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 @since tag SHOULD NOT be used to show the current version of an element, the
- @version tag MAY be used for that purpose.
- #### Examples
- ```php
- /**
- * This is Foo
- * @version MyApp 2.1.7
- * @since 2.0.0 introduced
- */
- class Foo
- {
- /**
- * Make a bar.
- *
- * @since 2.1.5 bar($arg1 = '', $arg2 = null)
- * introduced the optional $arg2
- * @since 2.1.0 bar($arg1 = '')
- * introduced the optional $arg1
- * @since 2.0.0 bar()
- * introduced new method bar()
- */
- public function bar($arg1 = '', $arg2 = null)
- {
- <...>
- }
- }
- ```
- ### 8.18. @struct
- TODO: specify details
- TODO: determine whether this is a correct approach
- ### 8.19. @subpackage [deprecated]
- The @subpackage tag is used to categorize "Structural Elements" into logical
- subdivisions.
- #### Syntax
- @subpackage [name]
- #### Description
- The @subpackage tag MAY be used as a counterpart or supplement to Namespaces.
- Namespaces provide a functional subdivision of "Structural Elements" where
- the @subpackage tag can provide a *logical* subdivision in which way the
- elements can be grouped with a different hierarchy.
- If, across the board, both logical and functional subdivisions are equal is it
- NOT RECOMMENDED to use the @subpackage tag, to prevent maintenance overhead.
- The @subpackage tag MUST only be used in a specific series of DocBlocks, as is
- described in the documentation for the @package tag.
- This tag MUST accompany a @package tag and MUST NOT occur more than once per
- DocBlock.
- #### Examples
- ```php
- /**
- * @package PSR
- * @subpackage Documentation\API
- */
- ```
- ### 8.20. @throws
- The @throws tag is used to indicate whether "Structural Elements" throw a
- specific type of exception.
- #### Syntax
- @throws ["Type"] [<description>]
- #### Description
- The @throws tag MAY be used to indicate that "Structural Elements" throw a
- specific type of error.
- The type provided with this tag MUST represent an object of the class Exception
- or any subclass thereof.
- This tag is used to present in your documentation which error COULD occur and
- under which circumstances. It is RECOMMENDED to provide a description that
- describes the reason an exception is thrown.
- It is also RECOMMENDED that this tag occurs for every occurrence of an
- exception, even if it has the same type. By documenting every occurrence a
- detailed view is created and the consumer knows for which errors to check.
- #### Examples
- ```php
- /**
- * Counts the number of items in the provided array.
- *
- * @param mixed[] $array Array structure to count the elements of.
- *
- * @throws InvalidArgumentException if the provided argument is not of type
- * 'array'.
- *
- * @return int Returns the number of elements.
- */
- function count($items)
- {
- <...>
- }
- ```
- ### 8.21. @todo
- The @todo tag is used to indicate whether any development activities should
- still be executed on associated "Structural Elements".
- #### Syntax
- @todo [description]
- #### Description
- The @todo tag is used to indicate that an activity surrounding the associated
- "Structural Elements" must still occur. Each tag MUST be accompanied by
- a description that communicates the intent of the original author; this could
- however be as short as providing an issue number.
- #### Examples
- ```php
- /**
- * Counts the number of items in the provided array.
- *
- * @todo add an array parameter to count
- *
- * @return int Returns the number of elements.
- */
- function count()
- {
- <...>
- }
- ```
- ### 8.22. @type
- You may use the @type tag to document the "Type" of the following
- "Structural Elements":
- * Constants, both class and global
- * Properties
- * Variables, both global and local scope
- #### Syntax
- @type ["Type"] [element_name] [<description>]
- #### Description
- The @type tag is the successor of the @var tag and serves the purpose of defining
- which type of data is contained in a Constant, Property or Variable.
- Each Constant or Property *definition* MUST be preceded by a DocBlock
- containing the @type tag. Each Variable, where the type is ambiguous or unknown,
- SHOULD be preceded by a DocBlock containing the @type tag. Any other
- variable MAY be preceeded with a similar DocBlock.
- The @type tag MUST contain the name of the element it documents. This is used
- when compound statements are used to define a series of Constants or Properties.
- Such a compound statement can only have one DocBlock while several items are
- represented.
- It is NOT RECOMMENDED to use the @var alias unless it is necessary in order for
- the application, or associated tools, to function correctly.
- #### Examples
- ```php
- /** @type int $int This is a counter. */
- $int = 0;
- // there should be no docblock here
- $int++;
- ```
- Or:
- ```php
- class Foo
- {
- /** @type string|null $description Should contain a description */
- protected $description = null;
- public function setDescription($description)
- {
- // there should be no docblock here
- $this->description = $description;
- }
- }
- ```
- Another example is to document the variable in a foreach explicitly; many IDEs
- use this information to help you with auto-completion:
- ```php
- /** @type \Sqlite3 $sqlite */
- foreach($connections as $sqlite) {
- // there should be no docblock here
- $sqlite->open('/my/database/path');
- <...>
- }
- ```
- Even compound statements may be documented:
- ```php
- class Foo
- {
- /**
- * @type string $name Should contain a description
- * @type string $description Should contain a description
- */
- protected $name, $description;
- }
- ```
- Or constants:
- ```php
- class Foo
- {
- /**
- * @type string MY_CONST1 Should contain a description
- * @type string MY_CONST2 Should contain a description
- */
- const MY_CONST1 = "1", MY_CONST2 = "2";
- }
- ```
- ### 8.22. @uses
- Indicates whether the current "Structural Element" consumes the
- "Structural Element", or project file, that is provided as target.
- #### Syntax
- @uses [file | "FQSEN"] [<description>]
- #### Description
- The @uses tag describes whether any part of the associated "Structural Element"
- uses, or consumes, another "Structural Element" or a file that is situated in
- the current project.
- When defining a reference to another "Structural Element" you can refer to a
- specific element by appending a double colon and providing the name of that
- element (also called the "FQSEN").
- Files that are contained in this project can be referred to by this tag. This
- can be used, for example, to indicate a relationship between a Controller and
- a template file (as View).
- This tag MUST NOT be used to indicate relations to elements outside of the
- system, so URLs are not usable. To indicate relations with outside elements the
- @see tag can be used.
- Applications consuming this tag, such as generators, are RECOMMENDED to provide
- a `@used-by` tag on the destination element. This can be used to provide a
- bi-directional experience and allow for static analysis.
- #### Examples
- ```php
- <?php
- /**
- * @uses \SimpleXMLElement::__construct()
- */
- function initializeXml()
- {
- <...>
- }
- ```
- ```php
- <?php
- /**
- * @uses MyView.php
- */
- function executeMyView()
- {
- <...>
- }
- ```
- The @var tag is a **deprecated** alias for `@type`. Please see the documentation
- for `@type` for details of its usage.
- ### 8.25. @version
- The @version tag is used to denote some description of "versioning" to an
- element.
- #### Syntax
- @version ["Semantic Version"] [<description>]
- #### Description
- Documents the current "version" of any element.
- This information can be used to generate a set of API Documentation where the
- consumer is informed about elements at a particular version.
- It is RECOMMENDED that the version number matches a semantic version number as
- described in the [Semantic Versioning Standard version 2.0][SEMVER2].
- Version vectors from Version Control Systems are also supported, though they
- MUST follow the form:
- name-of-vcs: $vector$
- A description MAY be provided, for the purpose of communicating any additional
- version-specific information.
- The @version tag MAY NOT be used to show the last modified or introduction
- version of an element, the @since tag SHOULD be used for that purpose.
- #### Examples
- ```php
- /**
- * File for class Foo
- * @version 2.1.7 MyApp
- * (this string denotes the application's overall version number)
- * @version @package_version@
- * (this PEAR replacement keyword expands upon package installation)
- * @version $Id$
- * (this CVS keyword expands to show the CVS file revision number)
- */
- /**
- * This is Foo
- */
- class Foo
- {
- <...>
- }
- ```
- ## Appendix A. Types
- ### ABNF
- type-expression = 1*(array-of-type-expression|array-of-type|type ["|"])
- array-of-type-expression = "(" type-expression ")[]"
- array-of-type = type "[]"
- type …
Large files files are truncated, but you can click here to view the full file