PageRenderTime 137ms CodeModel.GetById 75ms app.highlight 52ms RepoModel.GetById 2ms app.codeStats 0ms

/docs/PSR.md

http://github.com/phpDocumentor/phpDocumentor2
Markdown | 1464 lines | 1076 code | 388 blank | 0 comment | 0 complexity | 4caca718510d19c52ae0b0cbdeb5417c MD5 | raw file
   1PSR-n: PHPDoc
   2=============
   3
   4Author(s):
   5
   6    Mike van Riel (@mvriel) <mike.vanriel@naenius.com>
   7
   8Acknowledgements:
   9
  10    The authors wish to thank Chuck Burgess (@ashnazg),
  11    Gary Jones (@GaryJ) and all other people who commented on
  12    various versions of this proposal.
  13
  14Obsoletes:
  15
  16    De-facto PHPDoc Standard (http://www.phpdoc.org)
  17
  18## Table Of Contents
  19
  20    1. Introduction
  21    2. Conventions Used In This Document
  22    3. Definitions
  23    4. Basic Principles
  24    5. The PHPDoc Format
  25      5.1. Short Description
  26      5.2. Long Description
  27      5.3. Tags
  28        5.3.1. Tag Name
  29        5.3.2. Tag Signature
  30      5.4. Examples
  31    6. Inheritance
  32      6.1. Class Or Interface
  33      6.2. Function Or Method
  34      6.3. Constant Or Property
  35    7. Tags
  36      7.1.  @api
  37      7.2.  @author
  38      7.3.  @category [deprecated]
  39      7.4.  @copyright
  40      7.5.  @deprecated
  41      7.6.  @example
  42      7.7.  @global
  43      7.8.  @internal
  44      7.9.  @license
  45      7.10. @link
  46      7.11. @method
  47      7.12. @package
  48      7.13. @param
  49      7.14. @property
  50      7.15. @return
  51      7.16. @see
  52      7.17. @since
  53      7.18. @subpackage [deprecated]
  54      7.19. @throws
  55      7.20. @todo
  56      7.21. @type
  57      7.22. @uses
  58      7.23. @var
  59      7.24. @version
  60    Appendix A. Types
  61    Appendix B. Differences Compared With The De-facto PHPDoc Standard
  62
  63## 1. Introduction
  64
  65The main purpose of this PSR is to provide a complete and formal definition of
  66the PHPDoc standard. This PSR deviates from its predecessor, the de-facto PHPDoc
  67Standard associated with [phpDocumentor 1.x](http://www.phpdoc.org), to provide
  68support for newer features in the PHP language and to address some of the
  69shortcomings of its predecessor.
  70
  71This document SHALL NOT:
  72
  73* Describe a standard for implementing annotations via PHPDoc. Although it does
  74  offer versatility which makes it possible to create a subsequent PSR based on
  75  current practices. See [chapter 5.3](#53-tags) for more information on this
  76  topic.
  77* Describe best practices or recommendations for Coding Standards on the
  78  application of the PHPDoc standard. This document is limited to a formal
  79  specification of syntax and intention.
  80
  81## 2. Conventions Used In This Document
  82
  83The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  84"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  85document are to be interpreted as described in
  86[RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
  87
  88## 3. Definitions
  89
  90* "PHPDoc" is a section of documentation which provides information on several
  91  aspects of a "Structural Element".
  92
  93  > It is important to note that the PHPDoc and the DocBlock are two separate
  94  > entities. The DocBlock is the combination of a DocComment, which is a type
  95  > of comment, and a PHPDoc entity. It is the PHPDoc entity that describes the
  96  > Short Description, Long Description and Tags.
  97
  98* "Structural Element" is a collection of Programming Constructs which SHOULD be
  99  preceded by a DocBlock. The collection contains the following constructs:
 100
 101  * namespace
 102  * require(_once)
 103  * include(_once)
 104  * class
 105  * interface
 106  * trait
 107  * function (including methods)
 108  * property
 109  * constant
 110  * variables, both local and global scope.
 111
 112  It is RECOMMENDED to precede a "Structural Element" with a DocBlock with its
 113  definition and not with each usage.
 114
 115  Example:
 116
 117  ```php
 118  /** @type int This is a counter. */
 119  $int = 0;
 120
 121  // there should be no docblock here
 122  $int++;
 123  ```
 124
 125  Or:
 126
 127  ```php
 128  /**
 129   * This class acts as an example on where to position a DocBlock.
 130   */
 131  class Foo
 132  {
 133      /** @type string|null Should contain a description if available */
 134      protected $description = null;
 135
 136      /**
 137       * This method sets a description.
 138       *
 139       * @param string $description A text with a maximum of 80 characters.
 140       *
 141       * @return void
 142       */
 143      public function setDescription($description)
 144      {
 145          // there should be no docblock here
 146          $this->description = $description;
 147      }
 148  }
 149  ```
 150
 151  An example of use that falls beyond the scope of this Standard is to document
 152  the variable in a foreach explicitly; many IDEs use this information to help
 153  you with auto-completion.
 154
 155  This Standard does not cover this specific instance as a foreach is not
 156  considered to be a "Structural Element" but a Control Flow structure.
 157
 158  ```php
 159  /** @type \Sqlite3 $sqlite */
 160  foreach($connections as $sqlite) {
 161      // there should be no docblock here
 162      $sqlite->open('/my/database/path');
 163      <...>
 164  }
 165  ```
 166
 167* "DocComment" is a special type of comment which starts with `/**`, ends
 168  with `*/` and may contain any number of lines in between.
 169  In case a DocComment spans multiple lines should every line start with an
 170  asterisk that is aligned with the first asterisk of the opening clause.
 171
 172  Single line example:
 173
 174  ```php
 175  /** <...> */
 176  ```
 177
 178  Multiline example:
 179
 180  ```php
 181  /**
 182   * <...>
 183   */
 184  ```
 185
 186* "DocBlock" is a "DocComment" containing a single "PHPDoc" and represents the
 187  basic in-source representation.
 188
 189* "Tag" is a single piece of meta information regarding a "Structural Element"
 190  or a component thereof.
 191
 192* "Type" is the determination of what type of data is associated with an element.
 193  This is commonly used when determining the exact values of arguments, constants,
 194  properties and more.
 195
 196  See Appendix A for more detailed information about types.
 197
 198## 4. Basic Principles
 199
 200* A PHPDoc MUST always be contained in a "DocComment"; the combination of these
 201  two is called a "DocBlock".
 202
 203* A DocBlock MUST precede a "Structural Element"
 204
 205  > An exception to this principle is the File-level DocBlock which must be
 206  > placed at the top of a PHP source code file.
 207
 208## 5. The PHPDoc Format
 209
 210The PHPDoc format has the following [ABNF](http://www.ietf.org/rfc/rfc5234.txt)
 211definition:
 212
 213    PHPDoc            = [short-description] [long-description] [tags]
 214    short-description = *CHAR ("." 1*CRLF / 2*CRLF)
 215    long-description  = 1*(CHAR / inline-tag) 1*CRLF ; any amount of characters
 216                                                     ; with inline tags inside
 217    tags              = *(tag 1*CRLF)
 218    inline-tag        = "{" tag "}"
 219    tag               = "@" tag-name [tag-details]
 220    tag-name          = (ALPHA / "\") *(ALPHA / DIGIT / "\" / "-" / "_")
 221    tag-details       = *SP (SP tag-description / tag-signature)
 222    tag-description   = 1*CHAR
 223    tag-signature     = "(" *tag-argument ")"
 224    tag-argument      = *SP 1*CHAR [","] *SP
 225
 226Examples of use are included in chapter 5.4.
 227
 228### 5.1. Short Description
 229
 230A short description MUST contain an abstract of the "Structural Element"
 231defining the purpose. It is recommended for short descriptions to span a single
 232line or at most two but not more than that.
 233
 234A short description must end with either a full stop (.) followed by a line
 235break or two sequential line breaks.
 236
 237If a long description is provided then it MUST be preceded by a short
 238description. Otherwise the long description will be considered being the short
 239description until the stop of the short description is encountered.
 240
 241Tags do not necessarily have to be preceded by a short description.
 242
 243### 5.2. Long Description
 244
 245The long description is OPTIONAL but SHOULD be included when the
 246"Structural Element", which this DocBlock precedes, contains more operations, or
 247more complex operations, than can be described in the short description alone.
 248
 249Any application parsing the long description SHOULD support the Markdown
 250mark-up language for this field so that it is possible for the author to provide
 251formatting and a clear way of representing code examples.
 252
 253Common uses for the long description are (amongst others):
 254
 255* To provide more detail to the casual reader than the short description on
 256  what this method does.
 257* To specify of what child elements an input or output array, or object, is
 258  composed.
 259* To provide a set of common use cases or scenarios in which the
 260  "Structural Element" may be applied.
 261
 262### 5.3. Tags
 263
 264Tags provide a way for authors to supply concise meta-data regarding the
 265succeeding "Structural Element". They commonly consist of a name followed by
 266white-space and a description. The description MAY span multiple lines and MAY
 267follow a strict format dictated by the type of tag, as indicated by its name.
 268
 269The meta-data supplied by tags could result in a change of behaviour of the
 270succeeding "Structural Element", in which case the term "Annotation" is
 271commonly used instead of "Tag".
 272
 273A variation of this is where, instead of a description, a tag-signature is used;
 274in most cases the tag will in fact be an annotation. The tag-signature is able
 275to provide the annotation with parameters regarding its operation.
 276
 277If a tag-signature is present then there MUST NOT be a description present in
 278the same tag.
 279
 280Annotations will not be described in further detail in this specification as
 281this falls beyond the scope. This specification provides a basis on top of which
 282annotations may be implemented.
 283
 284#### 5.3.1. Tag Name
 285
 286Tag names indicate what type of information is represented by this tag or, in
 287case of annotations, which behaviour must be injected into the succeeding
 288"Structural Element".
 289
 290In support of annotations, it is allowable to introduce a set of tags designed
 291specifically for an individual application or subset of applications (and thus
 292not covered by this specification).
 293
 294These tags, or annotations, MUST provide a namespace by either
 295* prefixing the tag name with a PHP-style namespace, or by
 296* prefixing the tag name with a single vendor-name followed by a hyphen.
 297
 298Example of a tag name prefixed with a php-style namespace (the prefixing slash
 299is OPTIONAL):
 300
 301    @\Doctrine\Orm\Mapping\Entity()
 302
 303> *Note*: The PHPDoc Standard DOES NOT make assumptions on the meaning of a tag
 304> unless specified in this document or subsequent additions or extensions.
 305>
 306> This means that you CAN use namespace aliases as long as a prefixing namespace
 307> element is provided. Thus the following is legal as well:
 308>
 309>     @Mapping\Entity()
 310>
 311> Your own library or application may check for namespace aliases and make a
 312> FQCN from this; this has no impact on this standard.
 313
 314> *Important*: Individual Documentation Generation Applications (DGAs) MAY
 315> interpret namespaces that are registered with that application and apply
 316> custom behaviour.
 317
 318Example of a tag name prefixed with a vendor name and hyphen:
 319
 320    @phpdoc-event transformer.transform.pre
 321
 322Tag names that are not prefixed with a vendor or namespace MUST be described in
 323this specification (see chapter 7) and/or any official addendum.
 324
 325#### 5.3.2. Tag Signature
 326
 327Tag signatures are commonly used for annotations to supply additional meta-data
 328specific to the current tag.
 329
 330The supplied meta-data can influence the behavior of the owning annotation and
 331as such influence the behavior of the succeeding "Structural Element".
 332
 333The contents of a signature are to be determined by the tag type (as described
 334in the tag-name) and fall beyond the scope of this specification. However, a
 335tag-signature MUST NOT be followed by a description or other form of meta-data.
 336
 337### 5.4. Examples
 338
 339The following examples serve to illustrate the basic use of DocBlocks; it is
 340advised to read through the list of tags in chapter 7.
 341
 342A complete example could look like the following example:
 343
 344```php
 345/**
 346 * This is a short description.
 347 *
 348 * This is a long description. It may span multiple lines
 349 * or contain 'code' examples using the _Markdown_ markup
 350 * language.
 351 *
 352 * @see Markdown
 353 *
 354 * @param int        $parameter1 A parameter description.
 355 * @param \Exception $e          Another parameter description.
 356 *
 357 * @\Doctrine\Orm\Mapper\Entity()
 358 *
 359 * @return string
 360 */
 361function test($parameter1, $e)
 362{
 363}
 364```
 365
 366It is also allowed to omit the long description:
 367
 368```php
 369/**
 370 * This is a short description.
 371 *
 372 * @see Markdown
 373 *
 374 * @param int        $parameter1 A parameter description.
 375 * @param \Exception $parameter2 Another parameter description.
 376 *
 377 * @\Doctrine\Orm\Mapper\Entity()
 378 *
 379 * @return string
 380 */
 381function test($parameter1, $parameter2)
 382{
 383}
 384```
 385
 386Or even omit the tags section as well (though in the following example is not
 387encouraged as you are missing information on the parameters and return value):
 388
 389```php
 390/**
 391 * This is a short description.
 392 */
 393function test($parameter1, $parameter2)
 394{
 395}
 396```
 397
 398A DocBlock may also span a single line as shown in the following example.
 399
 400```php
 401/** @var \ArrayObject $array */
 402public $array = null;
 403```
 404
 405## 6. Inheritance
 406
 407PHPDoc's also have the ability to inherit information when the succeeding
 408"Structural Element" has a super-element (such as a super-class or a method with
 409the same name in a super-class or implemented in a super-interface).
 410
 411Every "Structural Element" MUST inherit the following PHPDoc parts by default:
 412
 413* [Short description](#51-short-description)
 414* [Long description](#52-long-description)
 415* A specific subset of [tags](#53-tags)
 416  * [@version](#724-version)
 417  * [@author](#72-author)
 418  * [@copyright](#74-copyright)
 419
 420Each specific "Structural Element" MUST also inherit a specialized subset as
 421defined in the sub-chapters.
 422
 423The PHPDoc parts MUST NOT be inherited when a replacement is available in the
 424sub-element. The exception to this rule is when the {@inheritdoc} inline tag is
 425present in the long description. When present the parser MUST insert the
 426super-element's long description at the location of the {@inheritdoc} inline
 427tag.
 428
 429Inheritance takes place from the root of a class hierarchy graph to its leafs.
 430This means that anything inherited in the bottom of the tree MUST 'bubble' up to
 431the top unless overridden.
 432
 433> Note: a special circumstance here would be when the Long Description must be
 434> overridden but the Short Description should stay intact. It would be difficult
 435> for a reader to distinguish which is overridden.
 436>
 437> In this case MUST the writer use the {@inheritdoc} inline tag as
 438> Short Description and override the Long Description with the intended text.
 439>
 440> Without the {@inheritdoc} inline tag MUST the reader interpret any text
 441> as if the Short Description would be overridden and MAY long description
 442> appear overridden if the block of text contains a Short Description ending
 443> as defined in the ABNF.
 444
 445### 6.1. Class Or Interface
 446
 447In addition to the inherited descriptions and tags as defined in this chapter's
 448root MUST a class or interface inherit the following tags:
 449
 450* [@package](#712-package)
 451
 452A class or interface SHOULD inherit the following deprecated tags if supplied:
 453
 454* [@subpackage](#718-subpackage)
 455
 456The @subpackage MUST NOT be inherited if the @package annotation of the
 457super-class (or interface) is not the same as the @package of the child class
 458(or interface).
 459
 460Example:
 461
 462```php
 463/**
 464 * @package    Framework
 465 * @subpackage Controllers
 466 */
 467class Framework_ActionController
 468{
 469    <...>
 470}
 471
 472/**
 473 * @package My
 474 *
 475class My_ActionController extends Framework_ActionController
 476{
 477    <...>
 478}
 479```
 480
 481In the example above the My_ActionController MUST not inherit the subpackage
 482_Controllers_.
 483
 484### 6.2. Function Or Method
 485
 486In addition to the inherited descriptions and tags as defined in this chapter's
 487root MUST a class or interface inherit the following tags:
 488
 489* [@param](#713-param)
 490* [@return](#715-return)
 491* [@throws](#719-throws)
 492
 493### 6.3. Constant Or Property
 494
 495In addition to the inherited descriptions and tags as defined in this chapter's
 496root MUST a class or interface inherit the following tags:
 497
 498* [@type](#721-type)
 499
 500A constant or property SHOULD inherit the following deprecated tags if supplied:
 501
 502* [@var](#723-var)
 503
 504## 7. Tags
 505
 506Unless specifically mentioned in the description MAY each tag occur zero or more
 507times in each "DocBlock".
 508
 509### 7.1. @api
 510
 511The @api tag is used to declare "Structural Elements" as being suitable for
 512consumption by third parties.
 513
 514#### Syntax
 515
 516    @api
 517
 518#### Description
 519
 520The @api tag represents those "Structural Elements" with a public visibility
 521which are intended to be the public API components for a library or framework.
 522Other "Structural Elements" with a public visibility serve to support the
 523internal structure and are not recommended to be used by the consumer.
 524
 525The exact meaning of "Structural Elements" tagged with @api MAY differ per
 526project. It is however RECOMMENDED that all tagged "Structural Elements" SHOULD
 527NOT change after publication unless the new version is tagged as breaking
 528Backwards Compatibility.
 529
 530#### Examples
 531
 532```php
 533/**
 534 * This method will not change until a major release.
 535 *
 536 * @api
 537 *
 538 * @return void
 539 */
 540 function showVersion()
 541 {
 542    <...>
 543 }
 544```
 545
 546### 7.2. @author
 547
 548The @author tag is used to document the author of any "Structural Element".
 549
 550#### Syntax
 551
 552    @author [name] [<email address>]
 553
 554#### Description
 555
 556The @author tag can be used to indicate who has created a"Structural Element"
 557or has made significant modifications to it. This tag MAY also contain an
 558e-mail address. If an e-mail address is provided it MUST follow
 559the author's name and be contained in chevrons, or angle brackets, and MUST
 560adhere to the syntax defined in RFC 2822.
 561
 562#### Examples
 563
 564```php
 565/**
 566 * @author My Name
 567 * @author My Name <my.name@example.com>
 568 */
 569```
 570
 571### 7.3. @category [deprecated]
 572
 573The @category tag is used to organize groups of packages together but is
 574deprecated in favour of occupying the top-level with the @package tag.
 575As such usage of this tag is NOT RECOMMENDED.
 576
 577#### Syntax
 578
 579    @category [description]
 580
 581#### Description
 582
 583The @category tag was meant in the original de-facto Standard to group several
 584"Structural Elements" their @packages into one category. These categories could
 585then be used to aid in the generation of API documentation.
 586
 587This was necessary since the @package tag as defined in the original Standard did
 588not contain more then one hierarchy level; since this has changed this tag SHOULD
 589NOT be used.
 590
 591Please see the documentation for `@package` for details of its usage.
 592
 593This tag MUST NOT occur more than once in a "DocBlock".
 594
 595#### Examples
 596
 597```php
 598/**
 599 * Page-Level DocBlock
 600 *
 601 * @category MyCategory
 602 * @package  MyPackage
 603 */
 604```
 605
 606### 7.4. @copyright
 607
 608The @copyright tag is used to document the copyright information of any
 609"Structural element".
 610
 611#### Syntax
 612
 613    @copyright <description>
 614
 615#### Description
 616
 617The @copyright tag defines who holds the copyright over the "Structural Element".
 618The copyright indicates with this tag applies to the "Structural Element" to
 619which it applies and all child elements unless otherwise noted.
 620
 621The format of the description if governed by the coding standard of each
 622individual project. It is RECOMMENDED to mention the year or years which are
 623covered by this copyright and the organization involved.
 624
 625#### Examples
 626
 627```php
 628/**
 629 * @copyright 1997-2005 The PHP Group
 630 */
 631```
 632
 633### 7.5. @deprecated
 634
 635The @deprecated tag is used to indicate which 'Structural elements' are
 636deprecated and are to be removed in a future version.
 637
 638#### Syntax
 639
 640    @deprecated [<version>] [<description>]
 641
 642#### Description
 643
 644The @deprecated tag declares that the associated 'Structural elements' will
 645be removed in a future version as it has become obsolete or its usage is otherwise
 646not recommended.
 647
 648This tag MAY also contain a version number up till which it is guaranteed to be
 649included in the software. Starting with the given version will the function be
 650removed or may be removed without further notice.
 651
 652If is RECOMMENDED (but not required) to provide an additional description stating
 653why the associated element is deprecated.
 654If it is superceded by another method it is RECOMMENDED to add a @see tag in the
 655same 'PHPDoc' pointing to the new element.
 656
 657#### Examples
 658
 659```php
 660/**
 661 * @deprecated
 662 * @deprecated 1.0.0
 663 * @deprecated No longer used by internal code and not recommended.
 664 * @deprecated 1.0.0 No longer used by internal code and not recommended.
 665 */
 666```
 667
 668### 7.6. @example
 669
 670The @example tag is used to link to an external source code file which contains
 671an example of use for the current "Structural element". An inline variant exists
 672with which code from an example file can be shown inline with the Long
 673Description.
 674
 675#### Syntax
 676
 677    @example [URI] [<description>]
 678
 679or inline:
 680
 681    {@example [URI] [:<start>..<end>]}
 682
 683#### Description
 684
 685The example tag refers to a file containing example code demonstrating the
 686purpose and use of the current "Structural element". Multiple example tags may
 687be used per "Structural element" in case several scenarios are described.
 688
 689The URI provided with the example tag is resolved according to the following
 690rules:
 691
 6921. If a URI is proceeded by a scheme or root folder specifier such as `phar://`,
 693   `http://`, `/` or `C:\` then it is considered to be an absolute path.
 6942. If the URI is deemed relative and a location for the example files has been
 695   provided then the path relative to the given location is resolved.
 6963. If the previous path was not readable or the user has not provided a path
 697   than the application should try to search for a folder examples in the
 698   same folder as the source file featuring the example tag. If found then an
 699   attempt to resolve the path by combining the relative path given in the
 700   example tag and the found folder should be made.
 7014. If the application was unable to resolve a path given the previous rules than
 702   it should check if a readable folder 'examples' is found in the root folder
 703   of the project containing the "Structural Element" his source file.
 704
 705   > The root folder of a project is the highest folder common to all files
 706   > that are being processed by a consuming application.
 707
 708If a consumer intends to display the contents of the example file then it is
 709RECOMMENDED to use a syntax highlighting solution to improve user experience.
 710
 711The rules as described above apply to both the inline as the normal tags. The
 712inline tag has 2 additional parameters with which to limit which lines of code
 713are shown in the Long Description. Due to this consuming applications MUST
 714show the example code in case an inline example tag is used.
 715
 716The start and end argument may be omitted but the ellipsis should remain in
 717case either is used to give a clear visual indication. The same rules as
 718specified with the [substr](http://nl.php.net/manual/en/function.substr.php)
 719function of PHP are in effect with regards to the start and end limit.
 720
 721> A consuming application MAY choose to support the limit format as used in the
 722> previous standard but it is deprecated per this PSR.
 723> The previous syntax was: {@example [URI] [<start>] [<end>]} and did not support
 724> the same rules as the substr function.
 725
 726#### Examples
 727
 728```php
 729/**
 730 * Counts the number of items.
 731 * {@example http://example.com/foo-inline.https:2..8}
 732 *
 733 * @example http://example.com/foo.phps
 734 *
 735 * @return integer Indicates the number of items.
 736 */
 737function count()
 738{
 739    <...>
 740}
 741```
 742
 743### 7.7. @global
 744
 745### 7.8. @internal
 746
 747The @internal tag is used to denote that the associated "Structural Element" is
 748a structure internal to this application or library. It may also be used inside
 749a long description to insert a piece of text that is only applicable for
 750the developers of this software.
 751
 752#### Syntax
 753
 754    @internal
 755
 756or inline:
 757
 758    {@internal [description]}}
 759
 760The inline version of this tag may, contrary to other inline tags, contain
 761text but also other inline tags. To increase readability and ease parsing should
 762the tag be terminated with a double closing brace, instead of a single one.
 763
 764#### Description
 765
 766The @internal tag can be used as counterpart of the @api tag, indicating that
 767the associated "Structural Element" is used purely for the internal workings of
 768this piece of software.
 769
 770When generating documentation from PHPDoc comments it is RECOMMENDED to hide the
 771associated element unless the user has explicitly indicated that internal elements
 772should be included.
 773
 774An additional use of @internal is to add internal comments or additional
 775description text inline to the Long Description. This may be done, for example,
 776to withhold certain business-critical or confusing information when generating
 777documentation from the source code of this piece of software.
 778
 779#### Examples
 780
 781Mark the count function as being internal to this project:
 782
 783```php
 784/**
 785 * @internal
 786 *
 787 * @return integer Indicates the number of items.
 788 */
 789function count()
 790{
 791    <...>
 792}
 793```
 794
 795```php
 796/**
 797 * Counts the number of Foo.
 798 *
 799 * {@internal Silently adds one extra Foo to compensate for lack of Foo }}
 800 *
 801 * @return integer Indicates the number of items.
 802 */
 803function count()
 804{
 805    <...>
 806}
 807```
 808
 809### 7.9. @license
 810
 811The @license tag is used to indicate which license is applicable for the associated
 812'Structural Elements'.
 813
 814#### Syntax
 815
 816    @license [<url>] [name]
 817
 818#### Description
 819
 820The @license tag provides the user with the name and URL of the license that is
 821applicable to 'Structural Elements' and any of their child elements.
 822
 823It is NOT RECOMMENDED to apply @license tags to any 'PHPDoc' other than
 824file-level PHPDocs as this may cause confusion which license applies at which
 825time.
 826
 827Whenever multiple licenses apply MUST there be one @license tag per applicable
 828license.
 829
 830Instead of providing a URL MAY an identifier as identified in the
 831[SPDX Open Source License Registry](http://www.spdx.org/licenses/) be provided
 832and SHOULD this be interpreted as if having the URL mentioned in the registry.
 833
 834#### Examples
 835
 836```php
 837/**
 838 * @license MIT
 839 * @license http://www.spdx.org/licenses/MIT MIT License
 840 */
 841```
 842
 843### 7.10. @link
 844
 845The @link tag indicates a custom relation between the associated
 846"Structural Element" and a website, which is identified by an absolute URI.
 847
 848#### Syntax
 849
 850    @link [URI] [description]
 851
 852or inline
 853
 854   {@link [URI] [description]}
 855
 856#### Description
 857
 858The @link tag can be used to define a relation, or link, between the
 859"Structural Element", or part of the long description when used inline,
 860to an URI.
 861
 862The URI MUST be complete and welformed as specified in RFC 2396.
 863
 864The @link tag MAY have a description appended to indicate the type of relation
 865defined by this occurrence.
 866
 867#### Examples
 868
 869```php
 870/**
 871 * @link http://example.com/my/bar Documentation of Foo.
 872 *
 873 * @return integer Indicates the number of items.
 874 */
 875function count()
 876{
 877    <...>
 878}
 879```
 880
 881```php
 882/**
 883 * This method counts the occurences of Foo.
 884 *
 885 * When no more Foo ({@link http://example.com/my/bar}) are given this
 886 * function will add one as there must always be one Foo.
 887 *
 888 * @return integer Indicates the number of items.
 889 */
 890function count()
 891{
 892    <...>
 893}
 894```
 895
 896### 7.11. @method
 897
 898The @method allows a class to know which 'magic' methods are callable.
 899
 900#### Syntax
 901
 902    @method [return type] [name]([type] [parameter], [...]) [description]
 903
 904#### Description
 905
 906The @method tag is used in situation where a class contains the __call() magic
 907method and defines some definite uses.
 908
 909An example of this is a child class whose parent has a __call() to have dynamic
 910getters or setters for predefined properties. The child knows which getters and
 911setters need to be present but relies on the parent class to use the __call()
 912method to provide it. In this situation, the child class would have a @method
 913tag for each magic setter or getter method.
 914
 915The @method tag allows the author to communicate the type of the arguments and
 916return value by including those types in the signature.
 917
 918When the intended method does not have a return value then the return type MAY
 919be omitted; in which case 'void' is implied.
 920
 921@method tags MUST NOT be used in a PHPDoc that is not associated with a
 922*class* or *interface*.
 923
 924#### Examples
 925
 926```php
 927class Parent
 928{
 929    public function __call()
 930    {
 931        <...>
 932    }
 933}
 934
 935/**
 936 * @method string getString()
 937 * @method void setInteger(integer $integer)
 938 * @method setString(integer $integer)
 939 */
 940class Child extends Parent
 941{
 942    <...>
 943}
 944```
 945
 946### 7.12. @package
 947
 948The @package tag is used to categorize "Structural Elements" into logical
 949subdivisions.
 950
 951#### Syntax
 952
 953    @package [level 1]\[level 2]\[etc.]
 954
 955#### Description
 956
 957The @package tag can be used as a counterpart or supplement to Namespaces.
 958Namespaces provide a functional subdivision of "Structural Elements" where the
 959@package tag can provide a *logical* subdivision in which way the elements can
 960be grouped with a different hierarchy.
 961
 962If, across the board, both logical and functional subdivisions are equal is
 963it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.
 964
 965Each level in the logical hierarchy MUST separated with a backslash (`\`) to
 966be familiar to Namespaces. A hierarchy MAY be of endless depth but it is
 967RECOMMENDED to keep the depth at less or equal than six levels.
 968
 969Please note that the @package applies to different "Structural Elements"
 970depending where it is defined.
 971
 9721. If the @package is defined in the *file-level* DocBlock then it only applies
 973   to the following elements in the applicable file:
 974
 975   * global functions
 976   * global constants
 977   * global variables
 978   * requires and includes
 979
 9802. If the @package is defined in a *namespace-level* or *class-level* DocBlock
 981   then the package applies to that namespace, class or interface and their
 982   contained elements.
 983   This means that a function which is contained in a namespace with the
 984   @package tag assumes that package.
 985
 986This tag MUST NOT occur more than once in a "DocBlock".
 987
 988#### Examples
 989
 990```php
 991/**
 992 * @package PSR\Documentation\API
 993 */
 994```
 995
 996### 7.13. @param
 997
 998### 7.14. @property
 999
1000### 7.15. @return
1001
1002The @return tag is used to document the return value of functions or methods.
1003
1004#### Syntax
1005
1006    @return <"Type"> [description]
1007
1008#### Description
1009
1010With the @return tag it is possible to document the return type and function of a
1011function or method. When provided it MUST contain a "Type" (See Appendix A)
1012to indicate what is returned; the description on the other hand is OPTIONAL yet
1013RECOMMENDED in case of complicated return structures, such as associative arrays.
1014
1015The @return tag MAY have a multi-line description and does not need explicit
1016delimiting.
1017
1018It is RECOMMENDED when documenting to use this tag with every function and
1019method. Exceptions to this recommendation are:
1020
10211. **constructors**, the @return tag MAY be omitted here, in which case an
1022   interpreter MUST interpret this as if `@return self` is provided.
10232. **functions and methods without a `return` value**, the @return tag MAY be
1024   omitted here, in which case an interpreter MUST interpret this as if
1025   `@return void` is provided.
1026
1027This tag MUST NOT occur more than once in a "DocBlock" and is limited to the
1028"DocBlock" of a "Structural Element" or type method or function.
1029
1030#### Examples
1031
1032```php
1033/**
1034 * @return integer Indicates the number of items.
1035 */
1036function count()
1037{
1038    <...>
1039}
1040```
1041
1042```php
1043/**
1044 * @return string|null The label's text or null if none provided.
1045 */
1046function getLabel()
1047{
1048    <...>
1049}
1050```
1051
1052### 7.16. @see
1053
1054### 7.17. @since
1055
1056#### Description
1057
1058It is NOT RECOMMENDED for this tag to occur more than once in a "DocBlock".
1059
1060### 7.18. @subpackage [deprecated]
1061
1062This tag MUST NOT occur more than once in a "DocBlock".
1063
1064### 7.19. @throws
1065
1066### 7.20. @todo
1067
1068### 7.21. @type
1069
1070You may use the @type tag to document the "Type" of the following
1071"Structural Elements":
1072
1073* Constants, both class and global
1074* Properties
1075* Variables, both global and local scope
1076
1077#### Syntax
1078
1079    @type <"Type"> [description]
1080
1081#### Description
1082
1083The @type tag is the successor of the @var tag and serves the purpose of defining
1084which type of data is contained in a Constant, Property or Variable.
1085
1086Each Constant or Property *definition* MUST be preceded by a DocBlock
1087containing the @type tag. Each Variable, where the type is ambiguous or unknown,
1088SHOULD be preceded by a DocBlock containing the @type tag. Any other
1089variable MAY be preceeded with a similar DocBlock.
1090
1091It is NOT RECOMMENDED to use the @var alias unless it is necessary in order for
1092the application, or associated tools, to function correctly.
1093
1094This tag MUST NOT occur more than once in a "DocBlock".
1095
1096#### Examples
1097
1098```php
1099/** @type int This is a counter. */
1100$int = 0;
1101
1102// there should be no docblock here
1103$int++;
1104```
1105
1106Or:
1107
1108```php
1109class Foo
1110{
1111  /** @type string|null Should contain a description if available */
1112  protected $description = null;
1113
1114  public function setDescription($description)
1115  {
1116      // there should be no docblock here
1117      $this->description = $description;
1118  }
1119}
1120```
1121
1122Another example is to document the variable in a foreach explicitly; many IDEs
1123use this information to help you with auto-completion:
1124
1125```php
1126/** @type \Sqlite3 $sqlite */
1127foreach($connections as $sqlite) {
1128    // there should be no docblock here
1129    $sqlite->open('/my/database/path');
1130    <...>
1131}
1132```
1133
1134### 7.22. @uses
1135
1136### 7.23. @var [deprecated]
1137
1138Is a **deprecated** alias for `@type`, please see the documentation for `@type`
1139for details of its usage.
1140
1141This tag MUST NOT occur more than once in a "DocBlock".
1142
1143### 7.24. @version
1144
1145## Appendix A. Types
1146
1147### ABNF
1148
1149    type-expression          = 1*(array-of-type-expression|array-of-type|type ["|"])
1150    array-of-type-expression = "(" type-expression ")[]"
1151    array-of-type            = type "[]"
1152    type                     = class-name|keyword
1153    class-name               = 1*CHAR
1154    keyword                  = "string"|"integer"|"int"|"boolean"|"bool"|"float"
1155                               |"double"|"object"|"mixed"|"array"|"resource"
1156                               |"void"|"null"|"callback"|"false"|"true"|"self"
1157
1158### Additional details
1159
1160When a "Type" is used the user will expect a value, or set of values, as
1161detailed below.
1162
1163When the "Type" may consist of multiple types then these MUST be separated
1164with the vertical bar sign (|). Any application supporting this specification MUST
1165recognize this and split the "Type" before processing.
1166
1167For example: `@return int|null`
1168
1169The value represented by "Type" can be an array. The type MUST be defined
1170following the format of one of the following options:
1171
11721. unspecified, no definition of the contents of the represented array is given.
1173   Example: `@return array`
1174
11752. specified containing a single type, the Type definition informs the reader of
1176   the type of each array element. Only one type is then expected as element for
1177   a given array.
1178
1179   Example: `@return int[]`
1180
1181   Please note that _mixed_ is also a single type and with this keyword it is
1182   possible to indicate that each array element contains any possible type.
1183
11843. specified containing multiple types, the Type definition informs the reader
1185   of the type of each array element. Each element can be of any of the given
1186   types.
1187   Example: `@return (int|string)[]`
1188
1189The supported atomic types are either a *valid class name* or *keyword*.
1190
1191### Valid Class Name
1192
1193A valid class name seen from the context where this type is mentioned. Thus
1194this may be either a Fully Qualified Class Name (FQCN) or if present in a
1195namespace a local name.
1196
1197> It is RECOMMENDED for applications to expand any local name into a FQCN
1198> for easier processing and comparisons.
1199
1200The element to which this type applies is either an instance of this class
1201or an instance of a class that is a (sub-)child to the given class.
1202
1203> Due to the above nature it is RECOMMENDED for applications that
1204> collect and shape this information to show a list of child classes
1205> with each representation of the class. This would make it obvious
1206> for the user which classes are acceptable as type.
1207
1208### Keyword
1209
1210A keyword defining the purpose of this type. Not every element is determined
1211by a class but still worth of a classification to assist the developer in
1212understanding the code covered by the DocBlock.
1213
1214> Note: most of these keywords are allowed as class names in PHP and as
1215> such are hard to distinguish from real classes. As such the keywords MUST
1216> be lowercase, as most class names start with an uppercase first character,
1217> and you SHOULD NOT use classes with these names in your code.
1218
1219> There are more reasons to not name classes with the names of these
1220> keywords but that falls beyond the scope of this specification.
1221
1222The following keywords are recognized by this PSR:
1223
12241.  'string', the element to which this type applies is a string of
1225    binary characters.
1226
12272.  'integer' or 'int', the element to which this type applies is a whole
1228    number or integer.
1229
12303.  'boolean' or 'bool', the element to which this type applies only has
1231    state true or false.
1232
12334.  'float' or 'double', the element to which this type applies is a continuous,
1234    or real, number.
1235
12365.  'object', the element to which this type applies is the instance of an
1237    undetermined class.
1238    This could be considered an alias for providing the class stdClass, as this
1239    is the base class of all classes, but the intention of the type differs.
1240
1241    Providing stdClass will imply the intention that the related element contains
1242    an actual object of class stdClass or direct descendant, whereas object
1243    implies that it is completely unknown of which class the contained
1244    object will be.
1245
12466.  'mixed', the element to which this type applies can be of any type as
1247    specified here. It is not known on compile time which type will be used.
1248
12497.  'array', the element to which this type applies is an array of values.
1250
12518.  'resource', the element to which this type applies is a resource per
1252    the definition of PHP at
1253    http://www.php.net/manual/en/language.types.resource.php.
1254
12559.  'void', this type is commonly only used when defining the return type of a
1256    method or function.
1257    The basic definition is that the element indicated with this type does not
1258    contain a value and the user should not rely on any retrieved value.
1259
1260    For example:
1261
1262    ```php
1263    /**
1264     * @return void
1265     */
1266    function outputHello()
1267    {
1268        echo 'Hello world';
1269    }
1270    ***
1271
1272    In the example above no return statement is specified and thus is the return
1273    value not determined.
1274
1275    Example 2:
1276
1277    ```php
1278    /**
1279     * @param boolean $hi when true 'Hello world' is echo-ed.
1280     *
1281     * @return void
1282     */
1283    function outputHello($quiet)
1284    {
1285        if ($quiet} {
1286            return;
1287        }
1288        echo 'Hello world';
1289    }
1290    ```
1291
1292    In this example the function contains a return statement without a given
1293    value. Because there is no actual value specified does this also constitute
1294    as type 'void'.
1295
129610. 'null', the element to which this type applies is a NULL value or, in
1297    technical terms, does not exist.
1298
1299    A big difference compared to void is that this type is used in any situation
1300    where the described element may at any given time contain an explicit NULL
1301    value.
1302
1303    Example:
1304
1305    ```php
1306    /**
1307     * @return null
1308     */
1309    function foo()
1310    {
1311        echo 'Hello world';
1312        return null;
1313    }
1314    ```
1315
1316    This type is commonly used in conjunction with another type to indicate that
1317    it is possible that nothing is returned.
1318
1319    Example:
1320
1321    ```
1322    /**
1323     * @param boolean $create_new When true returns a new stdClass.
1324     *
1325     * @return stdClass|null
1326     */
1327    function foo($create_new)
1328    {
1329        if ($create_new) {
1330            return new stdClass();
1331        }
1332
1333        return null;
1334    }
1335    ```
1336
1337
133811. 'callback', the element to which this type applies is a pointer to a
1339    function call. This may be any type of callback as defined in the PHP manual
1340    at http://php.net/manual/en/language.pseudo-types.php.
1341
134212. 'false' or 'true', the element to which this type applies will have
1343    the value true or false. No other value will be returned from this
1344    element.
1345
134613. 'self', the element to which this type applies is of the same Class,
1347    or any of its children, as which the documented element is originally
1348    contained.
1349
1350    For example:
1351
1352        Method C() is contained in class A. The DocBlock states
1353        that its return value is of type `self`. As such method C()
1354        returns an instance of class A.
1355
1356    This may lead to confusing situations when inheritance is involved.
1357
1358    For example (previous example situation still applies):
1359
1360        Class B extends Class A and does not redefine method C(). As such
1361        it is possible to invoke method C() from class B.
1362
1363    In this situation ambiguity may arise as `self` could be interpreted as
1364    either class A or B. In these cases `self` MUST be interpreted as being
1365    an instance of the Class where the DocBlock containing the `self` type
1366    is written or any of its child classes.
1367
1368    In the examples above `self` MUST always refer to class A or B, since
1369    it is defined with method C() in class A.
1370
1371    If method C() was to be redefined in class B, including the type
1372    definition in the DocBlock, then `self` would refer to class B or any
1373    of its children.
1374
1375    > Due to the above nature it is RECOMMENDED for applications that
1376    > collect and shape this information to show a list of child classes
1377    > with each representation of the class. This would make it obvious
1378    > for the user which classes are acceptable as type.
1379
1380## Appendix B. Differences Compared With The De-facto PHPDoc Standard
1381
1382This specification intends to improve upon the de-facto PHPDoc standard by
1383expanding syntax and deprecating redundant elements.
1384
1385The following changes may be observed and a concise rationale is provided.
1386
1387### Syntax Changes
1388
1389#### Added Support For Namespaces
1390
1391#### Added 'self' As "Type"
1392
1393#### Added Array Notation For "Type"
1394
1395#### Expanded Basic Syntax To Support Doctrine2/Symfony2 Style Annotations
1396
1397### Tag Additions
1398
1399#### @api
1400
1401Framework and library developers needed a way for consumers to distinguish
1402between public methods intended for internal use or public methods fit for
1403consuming.
1404
1405#### @type
1406
1407This tag is meant to replace @var and better convey the meaning and intention:
1408to tell the user which *type* of data is contained in the succeeding
1409"Structural Element".
1410
1411Additionally constants did not have a tag which identified the type of the
1412contained data. Instead of re-using @var, which is inappropriate since
1413a constant is not variable, or defining a *new* tag @const, which would make
1414usage of the right tag even more complex, a new tag @type was created to replace
1415@var and serve as new tag for constants.
1416
1417### Tag Changes
1418
1419#### @package
1420
1421The @package tag replaces the function of the @category and @subpackage by
1422allowing a layered hierarchy using the '\' operator.
1423
1424See the documentation on the @package tag for details.
1425
1426#### @ignore
1427
1428The @ignore tag has not been included in this specification as it is not a tag
1429but an annotation specific to phpDocumentor and derived documentation
1430generators.
1431
1432#### @link
1433
1434In the de-facto standard, introduced by phpDocumentor, @link supported the use
1435of internal locators for "Structural Element". This use is actually superceded
1436by the @see tag and thus removed.
1437
1438It is NOT RECOMMENDED to use the @link tag for referencing "Structural Elements".
1439
1440#### @method
1441
1442phpDocumentor had a different signature where the method name was repeated. Since
1443this repetition only caused overhead it has been removed in this specification.
1444
1445### Deprecated Tags
1446
1447#### @category
1448
1449The @package tag replaces the function of the @category and @subpackage by
1450allowing a layered hierarchy using the '\' operator.
1451
1452See the documentation on the @package tag for details.
1453
1454#### @subpackage
1455
1456The @package tag replaces the function of the @category and @subpackage by
1457allowing a layered hierarchy using the '\' operator.
1458
1459See the documentation on the @package tag for details.
1460
1461#### @var
1462
1463The @var tag is considered ambiguous and non-semantic; as such it is superceded
1464by the @type tag which also allows the type of constants to be documented.