From 796b9d9cd62ae7a7319b57c9331f3c351b50e98d Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Mon, 5 Aug 2013 19:35:15 +0200 Subject: [PATCH 01/64] Submit PHPDoc proposal and meta-document See https://github.com/phpDocumentor/phpDocumentor2/commit/0dbdbfa318d197279b414e5c0d1ffb142b31a528#docs/PSR.md for the original draft written by the same editor and contributors. This is a continuation of that version (hence the deeplink since the document will be removed from the repository). --- proposed/phpdoc-meta.md | 117 +++ proposed/phpdoc.md | 2006 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 2123 insertions(+) create mode 100644 proposed/phpdoc-meta.md create mode 100644 proposed/phpdoc.md diff --git a/proposed/phpdoc-meta.md b/proposed/phpdoc-meta.md new file mode 100644 index 000000000..b7b18777d --- /dev/null +++ b/proposed/phpdoc-meta.md @@ -0,0 +1,117 @@ +PHPDoc Meta Document +==================== + +1. Summary +---------- + +The purpose of documentation using PHPDoc is to provide a comprehensive but flexible way to describe a software system +at the smallest possible level of detail. This type of documentation aids contributors and consumers of your source +code to, for example, understand what type of information needs to be passed to specific methods or how to be able to +consume a class of the project that a consumer want to use. + +By documenting specific elements inside the source code will the documentation for that part of the source code be less +susceptible to becoming out of date. + +PHPDoc as a notation exists for more than ten years now, is heavily inspired by JavaDoc and currently in use by a +significant percentage of public PHP projects in the field. + +2. Why Bother? +-------------- + +PHPDocumentor has spearheaded and facilitated the growth of the PHPDoc notation but with the growing number of other +tools that use the PHPDoc notation it is becoming increasingly important to have an official and formal standard +instead of the de-facto status that is currently provided. + +An additional goal for this PSR is to deprecate obsolete elements and introduce new concepts and syntax to reflect the +current status of the PHP language, and to facilitate best practices and design patterns in use today and in the +foreseeable future. + +Pros: + +* Developers (consumers) have a common reference to refer to when confronted with PHPDoc. +* Projects and their Developers (contributors) have an authoritative reference which they can consult. +* IDE vendors can standardize the way they use PHPDoc to aid in concerns such as auto-completion and navigation. +* Projects using the PHPDoc data to complement their functionality, such as Documentation generators or applications + using annotations, will have a common language with their consumers. +* Missing functionality can be described and implemented by aforementioned stakeholders. + +Cons: + +* If there are different uses of elements in the PHPDoc notation then it is desirable for projects to align with this + specification, which will cost effort to introduce. +* Deprecation of well-known PHPDoc elements may lead to a period of confusion or resistance to the proposed changes.It + is for this reason that concepts are deprecated and not removed. +* Given the age of the current standard and widespread adoption it is not possible to introduce significant breaks in + backwards compatibility with the current practices without a significant risk of alienating existing users or vendors. + +3. Scope +-------- + +## 3.1 Goals + +* Provide a complete technical definition, or schema, of the PHPDoc notation. +* Introduce new concepts matching best practices or design patterns in use today and in the foreseeable future. +* Deprecate old concepts that are replaced by newer concepts or are no longer in use in today's PHP landscape. + +## 3.2 Non-Goals + +* This PSR does not provide a recommendation on how and when to use the concepts described in this document; + not a coding standard. +* This PSR facilitates the creation of annotations by allowing the notation needed for Symfony/Doctrine style + annotations but does not describe a style of annotations or which there are. The concept of annotations is only + alluded at and out of scope for this PSR. + +4. Approaches +------------- + +### 4.1 Chosen Approach + +We have decided to formalize the existing practices, observe non-documented usages, such as Doctrine-style +annotations, and observe feature requests with Documentation generators such as phpDocumentor. + +The combination of these should be described in sufficient detail as to reduce the amount of possible interpretation. + +In addition to the above the authors have taken care to provide for future expansions and tag additions that do not +affect the Syntax of PHPDoc itself. + +Pros: + +* Delivers a machine-parsable and verifyable specification. +* Well-rounded proposal due to the number of factors considered. + +Cons: + +* Technical and verbose. +* Can only be extended when the syntax is not affected. + +5. People +--------- + +### 5.1 Editor(s) + +* Mike van Riel + +### 5.2 Sponsors + +* Phil Sturgeon +* Not yet filled + +### 5.3 Contributors + +* Chuck Burgess +* Gary Jones + +6. Votes +-------- + +* **Entrance Vote: ** TBD +* **Acceptance Vote:** TBD + +7. Relevant Links +----------------- + +Most of the relevant links are mentioned in the PSR itself as support for individual chapters. + +_**Note:** Order descending chronologically._ + +* [Original draft](https://github.com/phpDocumentor/phpDocumentor2/commit/0dbdbfa318d197279b414e5c0d1ffb142b31a528#docs/PSR.md) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md new file mode 100644 index 000000000..e12fe9278 --- /dev/null +++ b/proposed/phpdoc.md @@ -0,0 +1,2006 @@ +PSR-n: PHPDoc +============= + +Author(s): + + Mike van Riel (@mvriel) + +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] [] + +#### 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 + */ +``` + +### 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 + +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 + +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] [] + +or inline: + + {@example [URI] [:..]} + +#### 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] [] []} 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 [] [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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +} +``` + +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 + +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 = class-name|keyword + class-name = 1*CHAR + keyword = "string"|"integer"|"int"|"boolean"|"bool"|"float" + |"double"|"object"|"mixed"|"array"|"resource" + |"void"|"null"|"callable"|"false"|"true"|"self" + |"static"|"$this" + +### Additional details + +When a "Type" is used the user will expect a value, or set of values, as +detailed below. + +When the "Type" may consist of multiple types then these MUST be separated +with the vertical bar sign (|). Any application supporting this specification MUST +recognize this and split the "Type" before processing. + +For example: `@return int|null` + +The value represented by "Type" can be an array. The type MUST be defined +following the format of one of the following options: + +1. unspecified, no definition of the contents of the represented array is given. + Example: `@return array` + +2. specified containing a single type, the Type definition informs the reader of + the type of each array element. Only one type is then expected as element for + a given array. + + Example: `@return int[]` + + Please note that _mixed_ is also a single type and with this keyword it is + possible to indicate that each array element contains any possible type. + +3. specified containing multiple types, the Type definition informs the reader + of the type of each array element. Each element can be of any of the given + types. + Example: `@return (int|string)[]` + +The supported atomic types are either a *valid class name* or *keyword*. + +### Valid Class Name + +A valid class name seen from the context where this type is mentioned. Thus +this may be either a Fully Qualified Class Name (FQCN) or if present in a +namespace a local name. + +> It is RECOMMENDED for applications to expand any local name into a FQCN +> for easier processing and comparisons. + +The element to which this type applies is either an instance of this class +or an instance of a class that is a (sub-)child to the given class. + +> Due to the above nature it is RECOMMENDED for applications that +> collect and shape this information to show a list of child classes +> with each representation of the class. This would make it obvious +> for the user which classes are acceptable as type. + +### Keyword + +A keyword defining the purpose of this type. Not every element is determined +by a class but still worthy of classification to assist the developer in +understanding the code covered by the DocBlock. + +> Note: most of these keywords are allowed as class names in PHP and as +> such are hard to distinguish from real classes. As such the keywords MUST +> be lowercase, as most class names start with an uppercase first character, +> and you SHOULD NOT use classes with these names in your code. + +> There are more reasons to not name classes with the names of these +> keywords but that falls beyond the scope of this specification. + +The following keywords are recognized by this PSR: + +1. 'string', the element to which this type applies is a string of + binary characters. + +2. 'integer' or 'int', the element to which this type applies is a whole + number or integer. + +3. 'boolean' or 'bool', the element to which this type applies only has + state true or false. + +4. 'float' or 'double', the element to which this type applies is a continuous, + or real, number. + +5. 'object', the element to which this type applies is the instance of an + undetermined class. + This could be considered an alias for providing the class stdClass, as this + is the base class of all classes, but the intention of the type differs. + + Providing stdClass will imply the intention that the related element contains + an actual object of class stdClass or direct descendant, whereas object + implies that it is completely unknown of which class the contained + object will be. + +6. 'mixed', the element to which this type applies can be of any type as + specified here. It is not known on compile time which type will be used. + +7. 'array', the element to which this type applies is an array of values. + +8. 'resource', the element to which this type applies is a resource per + the [definition of PHP][PHP_RESOURCE]. + +9. 'void', this type is commonly only used when defining the return type of a + method or function. + The basic definition is that the element indicated with this type does not + contain a value and the user should not rely on any retrieved value. + + For example: + + /** + * @return void + */ + function outputHello() + { + echo 'Hello world'; + } + + In the example above no return statement is specified and thus the return + value is not determined. + + Example 2: + + /** + * @param boolean $hi when true 'Hello world' is echo-ed. + * + * @return void + */ + function outputHello($quiet) + { + if ($quiet} { + return; + } + echo 'Hello world'; + } + + In this example the function contains a return statement without a given + value. Because there is no actual value specified, this also qualifies + as type 'void'. + +10. 'null', the element to which this type applies is a NULL value or, in + technical terms, does not exist. + + A big difference compared to void is that this type is used in any situation + where the described element may at any given time contain an explicit NULL + value. + + Example: + + /** + * @return null + */ + function foo() + { + echo 'Hello world'; + return null; + } + + This type is commonly used in conjunction with another type to indicate that + it is possible that nothing is returned. + + Example: + + /** + * @param boolean $create_new When true returns a new stdClass. + * + * @return stdClass|null + */ + function foo($create_new) + { + if ($create_new) { + return new stdClass(); + } + + return null; + } + + return null; + } + ``` + + +11. 'callable', the element to which this type applies is a pointer to a + function call. This may be any type of callable as defined in the PHP manual + about [pseudo-types][PHP_PSEUDO] or the section on [callable][PHP_CALLABLE]. + +12. 'false' or 'true', the element to which this type applies will have + the value true or false. No other value will be returned from this + element. + +13. 'self', the element to which this type applies is of the same Class as + which the documented element is originally contained. + + For example: + + Method C() is contained in class A. The DocBlock states + that its return value is of type `self`. As such method C() + returns an instance of class A. + + This may lead to confusing situations when inheritance is involved. + + For example (previous example situation still applies): + + Class B extends Class A and does not redefine method C(). As such + it is possible to invoke method C() from class B. + + In this situation ambiguity may arise as `self` could be interpreted as + either class A or B. In these cases `self` MUST be interpreted as being + an instance of the Class where the DocBlock containing the `self` type + is written. + + In the examples above `self` MUST always refer to class A, since it is + defined with method C() in class A. + + > Due to the above nature it is RECOMMENDED for applications that + > collect and shape this information to show a list of child classes + > with each representation of the class. This would make it obvious + > for the user which classes are acceptable as type. + +14. 'static', the element to which this type applies is of the same Class as + which the documented element is contained, or when encountered in a + subclass is of type of that subclass instead of the original class. + + This keyword behaves the same way as the 'static' keyword keyword (not + the static property or method modifier) as defined by PHP. + +15. '$this', the element to which this type applies is the same exact instance + as the current Class in the given context. As such this type is a stricter + version of 'static' as, in addition, the returned instance must not only + be of the same Class but also the same instance. + + This type is often used as return value for methods implementing the + [Fluent Interface][FLUENT] design pattern. + +[RFC2119]: http://www.ietf.org/rfc/rfc2119.txt +[RFC5234]: http://www.ietf.org/rfc/rfc5234.txt +[RFC2396]: http://www.ietf.org/rfc/rfc2396.txt +[SEMVER2]: http://www.semver.org +[PHP_SUBSTR]: http://nl.php.net/manual/en/function.substr.php +[PHP_RESOURCE]: http://www.php.net/manual/en/language.types.resource.php +[PHP_PSEUDO]: http://php.net/manual/en/language.pseudo-types.php +[PHP_CALLABLE]: http://php.net/manual/en/language.types.callable.php +[SPDX]: http://www.spdx.org/licenses +[DEFACTO]: http://www.phpdoc.org/docs/1.4/index.html +[PHPDOC.ORG]: http://www.phpdoc.org +[FLUENT]: http://en.wikipedia.org/wiki/Fluent_interface From 1572a8b30be43debf9d4fc9b2bd0e3a05b8c982a Mon Sep 17 00:00:00 2001 From: Chuck Burgess Date: Mon, 5 Aug 2013 13:38:32 -0500 Subject: [PATCH 02/64] textual changes from first pass review --- proposed/phpdoc-meta.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/proposed/phpdoc-meta.md b/proposed/phpdoc-meta.md index b7b18777d..c6c1d4a0a 100644 --- a/proposed/phpdoc-meta.md +++ b/proposed/phpdoc-meta.md @@ -6,23 +6,23 @@ PHPDoc Meta Document The purpose of documentation using PHPDoc is to provide a comprehensive but flexible way to describe a software system at the smallest possible level of detail. This type of documentation aids contributors and consumers of your source -code to, for example, understand what type of information needs to be passed to specific methods or how to be able to +code to, for example, understand what type of information needs to be passed to specific methods, or how to be able to consume a class of the project that a consumer want to use. -By documenting specific elements inside the source code will the documentation for that part of the source code be less +By documenting specific elements inside the source code the documentation for that part of the source code will be less susceptible to becoming out of date. -PHPDoc as a notation exists for more than ten years now, is heavily inspired by JavaDoc and currently in use by a +PHPDoc as a notation has existed for more than ten years now, is heavily inspired by JavaDoc, and is currently in use by a significant percentage of public PHP projects in the field. 2. Why Bother? -------------- -PHPDocumentor has spearheaded and facilitated the growth of the PHPDoc notation but with the growing number of other -tools that use the PHPDoc notation it is becoming increasingly important to have an official and formal standard +PHPDocumentor has spearheaded and facilitated the growth of the PHPDoc notation, but with the growing number of other +tools that use the PHPDoc notation, it is becoming increasingly important to have an official and formal standard instead of the de-facto status that is currently provided. -An additional goal for this PSR is to deprecate obsolete elements and introduce new concepts and syntax to reflect the +An additional goal for this PSR is to deprecate obsolete elements and introduce new concepts and syntaxes to reflect the current status of the PHP language, and to facilitate best practices and design patterns in use today and in the foreseeable future. @@ -37,11 +37,11 @@ Pros: Cons: -* If there are different uses of elements in the PHPDoc notation then it is desirable for projects to align with this +* If there are different uses of elements in the PHPDoc notation, then it is desirable for projects to align with this specification, which will cost effort to introduce. -* Deprecation of well-known PHPDoc elements may lead to a period of confusion or resistance to the proposed changes.It +* Deprecation of well-known PHPDoc elements may lead to a period of confusion or resistance to the proposed changes. It is for this reason that concepts are deprecated and not removed. -* Given the age of the current standard and widespread adoption it is not possible to introduce significant breaks in +* Given the age of the current standard and widespread adoption, it is not possible to introduce significant breaks in backwards compatibility with the current practices without a significant risk of alienating existing users or vendors. 3. Scope @@ -55,23 +55,23 @@ Cons: ## 3.2 Non-Goals -* This PSR does not provide a recommendation on how and when to use the concepts described in this document; - not a coding standard. +* This PSR does not provide a recommendation on how and when to use the concepts described in this document, + so it is not a coding standard. * This PSR facilitates the creation of annotations by allowing the notation needed for Symfony/Doctrine style - annotations but does not describe a style of annotations or which there are. The concept of annotations is only - alluded at and out of scope for this PSR. + annotations, but does not describe a style of annotations or which "defined annotations" exist in use. The concept of annotations is only + alluded at and is out of scope for this PSR. 4. Approaches ------------- ### 4.1 Chosen Approach -We have decided to formalize the existing practices, observe non-documented usages, such as Doctrine-style -annotations, and observe feature requests with Documentation generators such as phpDocumentor. +We have decided to formalize the existing practices, observe non-documented usages (such as Doctrine-style +annotations), and observe feature requests with Documentation generators (such as phpDocumentor). The combination of these should be described in sufficient detail as to reduce the amount of possible interpretation. -In addition to the above the authors have taken care to provide for future expansions and tag additions that do not +In addition to the above, the authors have taken care to provide for future expansions and tag additions that do not affect the Syntax of PHPDoc itself. Pros: From ad2a261441e4e209580862f4113c93d0b6efc35a Mon Sep 17 00:00:00 2001 From: Chuck Burgess Date: Mon, 5 Aug 2013 13:43:12 -0500 Subject: [PATCH 03/64] textual changes from second pass review --- proposed/phpdoc-meta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc-meta.md b/proposed/phpdoc-meta.md index c6c1d4a0a..5e8f012c3 100644 --- a/proposed/phpdoc-meta.md +++ b/proposed/phpdoc-meta.md @@ -59,7 +59,7 @@ Cons: so it is not a coding standard. * This PSR facilitates the creation of annotations by allowing the notation needed for Symfony/Doctrine style annotations, but does not describe a style of annotations or which "defined annotations" exist in use. The concept of annotations is only - alluded at and is out of scope for this PSR. + alluded to and is out of scope for this PSR. 4. Approaches ------------- From 6d1451dfcf12c11499a336d576f10399771e20d9 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 6 Aug 2013 08:28:22 +0200 Subject: [PATCH 04/64] Added Donald Gilbert as sponsor for phpdoc --- proposed/phpdoc-meta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc-meta.md b/proposed/phpdoc-meta.md index b7b18777d..bd4abfa21 100644 --- a/proposed/phpdoc-meta.md +++ b/proposed/phpdoc-meta.md @@ -94,7 +94,7 @@ Cons: ### 5.2 Sponsors * Phil Sturgeon -* Not yet filled +* Donald Gilbert ### 5.3 Contributors From 27d90d30bbf637d98c7613547474254c021b0ab4 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Tue, 13 Aug 2013 15:53:47 +0200 Subject: [PATCH 05/64] Fix indenting issues --- proposed/phpdoc.md | 68 ++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e12fe9278..8a4726af6 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -129,28 +129,28 @@ interpreted as described in [RFC 2119][RFC2119]. 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; - } - } + /** + * 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 @@ -187,9 +187,9 @@ interpreted as described in [RFC 2119][RFC2119]. Multiline example: ```php - /** - * <...> - */ + /** + * <...> + */ ``` * "DocBlock" is a "DocComment" containing a single "PHPDoc" structure and @@ -508,10 +508,10 @@ Some tags may even feature an "Inline PHPDoc" as shown in the following example. * @return integer * } */ - class MyMagicClass - { - ... - } +class MyMagicClass +{ + ... +} ``` ## 6. Inheritance @@ -690,10 +690,10 @@ Backwards Compatibility. * * @return void */ - function showVersion() - { - <...> - } +function showVersion() +{ + <...> +} ``` ### 8.2. @author @@ -1675,7 +1675,6 @@ bi-directional experience and allow for static analysis. #### Examples ```php - Date: Sat, 17 Aug 2013 11:27:52 +0100 Subject: [PATCH 06/64] Remove extraneous lines from null keyword example --- proposed/phpdoc.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 8a4726af6..0f8c24bb9 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1933,11 +1933,6 @@ The following keywords are recognized by this PSR: return null; } - return null; - } - ``` - - 11. 'callable', the element to which this type applies is a pointer to a function call. This may be any type of callable as defined in the PHP manual about [pseudo-types][PHP_PSEUDO] or the section on [callable][PHP_CALLABLE]. From 99dad5cdc69ebe29f875ed75350559f95312af88 Mon Sep 17 00:00:00 2001 From: Jon Cave Date: Sat, 17 Aug 2013 11:29:10 +0100 Subject: [PATCH 07/64] Don't use single type notation for mixed type arrays --- proposed/phpdoc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 8a4726af6..1eb70dee0 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -632,7 +632,7 @@ Example: /** * Initializes this class with the given options. * - * @param string[] $options { + * @param array $options { * @type boolean $required Whether this element is required * @type string $label The display name for this element * } @@ -1230,7 +1230,7 @@ an option array with 2 elements: 'required' and 'label'. /** * Initializes this class with the given options. * - * @param string[] $options { + * @param array $options { * @type boolean $required Whether this element is required * @type string $label The display name for this element * } From 7b41a17f0e3502c3f1a64a0f27335aa2300230c6 Mon Sep 17 00:00:00 2001 From: JDGrimes Date: Tue, 20 Aug 2013 10:24:06 -0400 Subject: [PATCH 08/64] Fixing internal links to the tags Fixing links to the Tags, which has been moved from section 7, and is now section 8. Also fixing @uses to be 8.23 instead of a second 8.22. (I also noticed there is a missing section that is in the index "Describing anonymous functions", but I didn't touch that). --- proposed/phpdoc.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index b4247c5d8..5e04958c7 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -525,9 +525,9 @@ 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) + * [@version](#825-version) + * [@author](#82-author) + * [@copyright](#84-copyright) Each specific "Structural Element" MUST also inherit a specialized subset as defined in the sub-chapters. @@ -559,11 +559,11 @@ the top unless overridden. 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) +* [@package](#812-package) A class or interface SHOULD inherit the following deprecated tags if supplied: -* [@subpackage](#718-subpackage) +* [@subpackage](#819-subpackage-deprecated) 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 @@ -598,20 +598,20 @@ _Controllers_. 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) +* [@param](#813-param) +* [@return](#815-return) +* [@throws](#820-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) +* [@type](#822-type) A constant or property SHOULD inherit the following deprecated tags if supplied: -* [@var](#723-var) +* [@var](#824-var-deprecated) ## 7. Describing hashes @@ -1641,7 +1641,7 @@ class Foo } ``` -### 8.22. @uses +### 8.23. @uses Indicates whether the current "Structural Element" consumes the "Structural Element", or project file, that is provided as target. @@ -1694,8 +1694,10 @@ function executeMyView() } ``` +### 8.24. @var [deprecated] + The @var tag is a **deprecated** alias for `@type`. Please see the documentation -for `@type` for details of its usage. +for [@type](#822-type) for details of its usage. ### 8.25. @version From 87623ece16097c391a9cf59287e0bbe6b4fff444 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 20 Aug 2013 23:41:09 +0200 Subject: [PATCH 09/64] #6: Add Generics notation description and refactor ABNF --- proposed/phpdoc.md | 84 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 58 insertions(+), 26 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e12fe9278..0d2d1b57c 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1755,48 +1755,79 @@ class Foo ### ABNF - type-expression = 1*(array-of-type-expression|array-of-type|type ["|"]) - array-of-type-expression = "(" type-expression ")[]" - array-of-type = type "[]" - type = class-name|keyword - class-name = 1*CHAR - keyword = "string"|"integer"|"int"|"boolean"|"bool"|"float" - |"double"|"object"|"mixed"|"array"|"resource" - |"void"|"null"|"callable"|"false"|"true"|"self" - |"static"|"$this" + A Type has the following [ABNF][RFC5234] definition: -### Additional details + ; the vertical bar sign in the type-expression MUST be used as separator when multiple elements are used + type-expression = 1*((array / type) ["|"]) + array = "array" / (type / array-expression / array) "[]" / generic + type = class-name / keyword + array-expression = "(" type-expression ")" + generic = collection-type "<" [type-expression "," *1SP] type-expression">" + collection-type = class-name / "array" + class-name = 1*ALPHA *(ALPHA / "_" / "\") + keyword = "string" / "integer" / "int" / "boolean" / "bool" / "float" / "double" / "object" + keyword =/ "mixed" / "resource" / "void" / "null" / "callable" / "false" / "true" / "self" + keyword =/ "static" / "$this" -When a "Type" is used the user will expect a value, or set of values, as -detailed below. +### Details -When the "Type" may consist of multiple types then these MUST be separated -with the vertical bar sign (|). Any application supporting this specification MUST -recognize this and split the "Type" before processing. +When a "Type" is used the user will expect a value, or set of values, as detailed below. + +When the "Type" consists of multiple types then these MUST be separated with the vertical bar sign (|). Any +interpreter supporting this specification MUST recognize this and split the "Type" before evaluating. For example: `@return int|null` -The value represented by "Type" can be an array. The type MUST be defined -following the format of one of the following options: +#### Arrays + +The value represented by "Type" can be an array. The type MUST be defined following the format of one of the +following options: 1. unspecified, no definition of the contents of the represented array is given. Example: `@return array` -2. specified containing a single type, the Type definition informs the reader of - the type of each array element. Only one type is then expected as element for - a given array. +2. specified containing a single type, the Type definition informs the reader of the type of each array value. Only one + type is then expected for each value in a given array. Example: `@return int[]` - Please note that _mixed_ is also a single type and with this keyword it is - possible to indicate that each array element contains any possible type. + Please note that _mixed_ is also a single type and with this keyword it is possible to indicate that each array + value contains any possible type. -3. specified containing multiple types, the Type definition informs the reader - of the type of each array element. Each element can be of any of the given - types. +3. specified as containing multiple types, the Type definition informs the reader of the type of each array value. + Each value can be of any of the given types. Example: `@return (int|string)[]` -The supported atomic types are either a *valid class name* or *keyword*. +4. specified using the Generics notation, see the next chapter "Collections" for a description on this notation. + +#### Collections + +The value represented by "Type" can also be a [Collection][COLLECTION], a class that contains a list of keys with +values. Collections can be denoted using a format derived from Generics in Java; as such aptly named Generics-style +notation. + +With Generics-style notation it is REQUIRED to specify a class name, or the array keyword, followed by the type of +the values enclosed with angular brackets. + +Example: to indicate that this element returns an object of class ArrayObject that only contains a series of strings. + + @return \ArrayObject + +The type of the values in a Collection MAY be another array and even another Collection, + + @return \ArrayObject<\ArrayObject> + +A Collection MAY optionally define the type of the keys of said Collection by adding an additional type definition +between the angular brackets before the identifier denoting the values' type. These two should be separated by a comma. + +Example: to declare an ArrayObject collection containing a list of strings with integer keys. + + @return \ArrayObject + +The type of a value, or key, MAY consist of several different types, this can be represented by separating each +individual type with a vertical bar sign between the angular brackets. + + @return \ArrayObject ### Valid Class Name @@ -2004,3 +2035,4 @@ The following keywords are recognized by this PSR: [DEFACTO]: http://www.phpdoc.org/docs/1.4/index.html [PHPDOC.ORG]: http://www.phpdoc.org [FLUENT]: http://en.wikipedia.org/wiki/Fluent_interface +[COLLECTION]: http://en.wikipedia.org/wiki/Collection_(abstract_data_type) From 9b232fb335fa0187b6b52e3c836567662817144d Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Thu, 29 Aug 2013 11:51:20 +0200 Subject: [PATCH 10/64] Update PSR number to PSR-5 --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 3cca9e487..05778ba2f 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1,4 +1,4 @@ -PSR-n: PHPDoc +PSR-5: PHPDoc ============= Author(s): From 761afeb804e64bb683a189a6562232e1c5111c82 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Sep 2013 07:40:33 +0200 Subject: [PATCH 11/64] #16: Improve definition of DocComment and object --- proposed/phpdoc.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 05778ba2f..66d41023a 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -169,14 +169,15 @@ interpreted as described in [RFC 2119][RFC2119]. } ``` -* "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. +* "DocComment" is a special type of comment which MUST - 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. + - start with the character sequence `/**` followed by a whitespace character + - end with `*/` and + - have zero or more lines in between. + + In case a DocComment spans multiple lines then every line MUST start with + an asterisk (`*`) that SHOULD be aligned with the first asterisk of the + opening clause. Single line example: @@ -1876,13 +1877,6 @@ The following keywords are recognized by this PSR: 5. 'object', the element to which this type applies is the instance of an undetermined class. - This could be considered an alias for providing the class stdClass, as this - is the base class of all classes, but the intention of the type differs. - - Providing stdClass will imply the intention that the related element contains - an actual object of class stdClass or direct descendant, whereas object - implies that it is completely unknown of which class the contained - object will be. 6. 'mixed', the element to which this type applies can be of any type as specified here. It is not known on compile time which type will be used. From a7c09ca680b2ca0f2be4cc9451948a333411b7d6 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Sep 2013 07:48:04 +0200 Subject: [PATCH 12/64] #16: Update Type ABNF according to the suggestion of @nikic @nikic has pointed out several shortcomings to the ABNF for types, his suggestion is a solid improvement to the BNF and has been used. One modification has been made; the 1*SP in the generic definition has been replaced with *SP to allow zero spaces as well. --- proposed/phpdoc.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 66d41023a..e1294dd6e 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1756,19 +1756,19 @@ class Foo ### ABNF - A Type has the following [ABNF][RFC5234] definition: +A Type has the following [ABNF][RFC5234] definition: - ; the vertical bar sign in the type-expression MUST be used as separator when multiple elements are used - type-expression = 1*((array / type) ["|"]) - array = "array" / (type / array-expression / array) "[]" / generic - type = class-name / keyword + type-expression = type *("|" type) + type = class-name / keyword / array + array = (type / array-expression) "[]" / generic array-expression = "(" type-expression ")" - generic = collection-type "<" [type-expression "," *1SP] type-expression">" + generic = collection-type "<" [type-expression "," *SP] type-expression ">" collection-type = class-name / "array" - class-name = 1*ALPHA *(ALPHA / "_" / "\") - keyword = "string" / "integer" / "int" / "boolean" / "bool" / "float" / "double" / "object" - keyword =/ "mixed" / "resource" / "void" / "null" / "callable" / "false" / "true" / "self" - keyword =/ "static" / "$this" + class-name = ["\"] label *("\" label) + label = (ALPHA / %x7F-FF) *(ALPHA / DIGIT / %x7F-FF) + keyword = "array" / "bool" / "boolean" / "callable" / "double" / "false" / "float" / "int" / "integer" + keyword =/ "mixed" / "null" / "object" / "resource" / "self" / "static" / "string" / "true" / "void" + keyword =/ "$this" ### Details From 1853628be8e05e077fb034d44707d02876bee659 Mon Sep 17 00:00:00 2001 From: Gary Jones Date: Mon, 23 Sep 2013 09:55:50 +0100 Subject: [PATCH 13/64] Fix nested lists Markdown wasn't seeing the unordered list as nested, so the list items were appearing as: 1. * * * 1. It now appears correctly as: 1. * * * 2. --- proposed/phpdoc.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e1294dd6e..27f9c5393 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1161,11 +1161,10 @@ 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 + * 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 From 2d6149d71a3f7c1c9b23c8c744ef3e8a9c3c99d6 Mon Sep 17 00:00:00 2001 From: Gary Jones Date: Mon, 23 Sep 2013 10:29:34 +0100 Subject: [PATCH 14/64] Fix typo --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e1294dd6e..b7c920bfa 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -772,7 +772,7 @@ 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 +The format of the description is 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. From dd20d569d375bf0442475e2ba82800b8f3b96d1a Mon Sep 17 00:00:00 2001 From: Gary Jones Date: Tue, 24 Sep 2013 01:33:35 +0100 Subject: [PATCH 15/64] Use File-Level, not Page-Level, for consistency There are several mentions of "File-Level" throughout the documentation, but one inconsistent reference to the previous term of "Page-Level". --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e1294dd6e..57d0a9e21 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -750,7 +750,7 @@ This tag MUST NOT occur more than once in a "DocBlock". ```php /** - * Page-Level DocBlock + * File-Level DocBlock * * @category MyCategory * @package MyPackage From 8556da66e55e09685239be8ecdf9690f6170abce Mon Sep 17 00:00:00 2001 From: Alex Russell Date: Thu, 10 Oct 2013 10:29:58 +0100 Subject: [PATCH 16/64] Update @return tag exceptions for constructors, fixes #18 Constructors should assume `@return $this` rather than `@return self` as per discussion in bug #18 --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e1294dd6e..302940188 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1306,7 +1306,7 @@ 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. + interpreter MUST interpret this as if `@return $this` 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. From a0f91414d8dc3f87e22b043cb3750b9f123a73c0 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Fri, 11 Oct 2013 21:09:50 +0200 Subject: [PATCH 17/64] Reword PSR-4 to be more verbose and complete --- proposed/psr-4-autoloader/psr-4-autoloader.md | 250 ++++++++++++------ 1 file changed, 173 insertions(+), 77 deletions(-) diff --git a/proposed/psr-4-autoloader/psr-4-autoloader.md b/proposed/psr-4-autoloader/psr-4-autoloader.md index c00ea4d87..f29b48067 100644 --- a/proposed/psr-4-autoloader/psr-4-autoloader.md +++ b/proposed/psr-4-autoloader/psr-4-autoloader.md @@ -1,119 +1,215 @@ PSR-4: Autoloader ================= +1. Introduction +--------------- + +The goal for this specification is two-fold: + +1. As an extension to PSR-0, and to provide an alternative option for + applications to determine the location of a file resource on a medium, + as supported by PHP, when a "Fully Qualified Class Name" is provided. + +2. As a specification for software maintainers on how to name and structure + namespaces in an application so that a uniform representation develops. + + This will aid developers by + + - improving navigation and searchability of PHP source code due to + recognizability. + - preventing conflicts and assisting with naming and structuring for + maintainers. + - assisting applications to automatically find classes without the need for + include or require statements, also known as 'autoloading'. + +The location of a file resource is often determined by a specialized library, +or component, to which we refer as an autoloader. This name provides no further +significance in the context of this document but is provided to clarify when +and where file resource locations are determined in real world situations. + +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](http://tools.ietf.org/html/rfc2119). +3. Scope +-------- -1. Overview ------------ +This specification is partly backwards incompatible with PSR-0. Where a +conflict occurs the rules in this specification precede, or override, the +rules in PSR-0. -The following describes the mandatory requirements that must be adhered to -for autoloader interoperability, by mapping namespaces to file system paths. +4. Definitions +-------------- +- "Class" refers to PHP classes, interfaces, and traits alike. -2. Definitions --------------- +- "Fully Qualified Class Name" is a string representing the complete class + name, including its Namespace. For the scope of this specification it + MUST NOT include the leading Namespace separator. + +- "Namespace Part" is any individual section of a "Fully Qualified Class + Name" or Namespace. + + An example of this would be the "Fully Qualified Class Name" + `Acme\Log\Formatter\LineFormatter`, where the "Namespace Parts" here are + `Acme`, `Log`, and `Formatter`. + + A "Namespace Part" MUST NOT include a leading or trailing Namespace separator. + +- "Namespace Prefix" is a series of "Namespace Parts", always starting with + the first part, of a Namespace or "Fully Qualified Class Name". + + Example: -- **Class**: The term "class" refers to PHP classes, interfaces, and traits. + Given a "Fully Qualified Class Name" of + `Acme\Log\Formatter\LineFormatter`, the "Namespace Prefix" could be + `Acme\`, `Acme\Log\`, or `Acme\Log\Formatter\`. -- **Fully Qualified Class Name**: The full namespace and class name. The - "fully qualified class name" MUST NOT include the leading namespace - separator. + A "Namespace Prefix" MUST NOT include a leading namespace separator, but + MUST include a trailing namespace separator. -- **Namespace Name**: Given a "fully qualified class name" of - `Acme\Log\Formatter\LineFormatter`, the "namespace names" are `Acme`, `Log`, and `Formatter`. A - namespace name MUST NOT include a leading or trailing namespace separator. - -- **Namespace Prefix**: Given a "fully qualified class name" of - `Acme\Log\Formatter\LineFormatter`, the "namespace prefix" could be `Acme\`, `Acme\Log\`, or - `Acme\Log\Formatter\`. The "namespace prefix" MUST NOT include a leading namespace - separator, but MUST include a trailing namespace separator. +- "Base Location" is a location from where an application or library should + start scanning for a File Resource applicable to a given "Fully Qualified + Class Name". -- **Relative Class Name**: The parts of the "fully qualified class name" that - appear after the "namespace prefix". Given a "fully qualified class name" of - `Acme\Log\Formatter\LineFormatter` and a "namespace prefix" of `Acme\Log\`, the "relative - class name" is `Formatter\LineFormatter`. The "relative class name" MUST NOT include a - leading namespace separator. + A "Base Location" can be related to a "Namespace Prefix" in order to 'skip' + "Namespace Parts" and to lessen the depth of the applicable File Resource + Location. -- **Base Directory**: The directory path in the file system where the files - for "relative class names" have their root. Given a namespace prefix of - `Acme\Log\`, the "base directory" could be `./src/`. - The "base directory" MUST include a trailing directory separator. + For example: -- **Mapped File Name**: The path in the file system resulting from the - transformation of a "fully qualified class name". Given a "fully qualified - class name" of `Acme\Log\Formatter\LineFormatter`, a namespace prefix of `Acme\Log\`, and a - "base directory" of `./src/`, the "mapped file name" - MUST be `./src/Formatter/LineFormatter.php`. + A "Base Location" can be the folder `./src/`; in which case attempting + to locate the "Fully Qualified Class Name" + `Acme\Log\Formatter\LineFormatter` will result in the File Resource + Location `./src/Acme/Log/Formatter/LineFormatter.php`. + Should the "Base Location" `./src/` be related to the "Namespace + Prefix" `Acme\Log` then the File Resource Location would become + `./src/Formatter/LineFormatter.php`. + + See chapter 4 for more information on the translation process. + + The "Base Location" MUST include a trailing separator applicable to the + respective location scheme; in case of physical files this means the + directory separator. + +- "Mapped File Location" is the end-product of the translation of a + "Fully Qualified Class Name" and represents a File Resource Location. 3. Specification ---------------- -### 3.1. General +For an application to be able to translate a "Fully Qualified Class Name" this +specification prescribes that specific principles, or conditions, MUST be +fulfilled or taken into account. + +When these principles are met an application can translate the "Fully +Qualified Class Name" according to the rules as described in the appropriate +chapter below. + +Aside from technical considerations this specification also imposes +requirements according to best practices on software developers. Software +developers that wish to comply with this specification MUST also write their +software using these same principles. + +The principles are mentioned as the first chapter given that they are universal +to the way developers MUST deal with namespaces and "Fully Qualified Class +Names", the subsequent chapter will describe the process of translating a +namespace to a File Resource Location. + +### 3.1. Principles + +1. A "Fully Qualified Class Name" MUST begin with one or more "Namespace Parts" + and MUST end with a "Class" name. + + For example: + + With a "Fully Qualified Class Name" of `Acme\Log\Baz`, the + "Namespace Parts" are `Acme\Log` and the "Class" name is `Baz`. + +2. The first "Namespace Part" of a namespace or "Fully Qualified Class Name" + MUST be a vendor name unique to the developer. This will prevent clashes + between different pieces of software, such as libraries and components. + + It is RECOMMENDED for the second "Namespace Part" to be a unique name + describing the application or library but this is not required. + + An example of this concept is: + + `\Vendor\ClassName` -1. A fully-qualified namespace and class must have the following - structure `\\(\)*` + or when the application name is used as second "Namespace Part": -2. Each namespace must have a top-level namespace ("Vendor Name"). + `\Vendor\Application\ClassName` -3. Each namespace can have as many sub-namespaces as it wishes. +3. This specification does not impose a limit on the number of + "Namespace Parts" used by the developer of an application or library. It is + however RECOMMENDED to limit the depth. -4. Each namespace separator is converted to a `DIRECTORY_SEPARATOR` when - loading from the file system. +4. The File Location for a "Class" MUST match the capitalization of the + "Class" and its "Namespace Parts". -5. The "fully qualified class name" MUST begin with a "namespace name", which -MAY be followed by one or more additional namespace names, and MUST end in -a class name. +### Translating a "Fully Qualified Class Name" into a File Resource location - > **Example:** With a "fully qualified class name" of `Acme\Log\Baz`, - > the "namespace name is `Acme\Log` and the class name is `Baz`. +A relationship MAY be present between a "Namespace Prefix" and a "Base +Location". This relationship allows an application or library to locate a +"Class" based on its "Fully Qualified Class Name". If no relationship is defined +then the "Namespace Prefix" is considered to be empty. -6. A "namespace prefix" MUST correspond to at least one "base directory". +The method with which a relationship is defined is not within the scope +of this specification and is left up to the specific implementation. - > **Example:** Any one of these examples would be valid if used - > individually: - > - > * \Acme\Log -> ./ - > * \Acme\Log -> ./src/ - > * \Acme\Log -> ./src/foo/ +To translate a "Fully Qualified Class Name" into a "Mapped File Location" an +application or library MUST apply the following steps, in sequence. -7. A "namespace prefix" MAY correspond to more than one "base directory". The -order in which an autoloader will attempt to map the file is not in the scope -of this specification, but the consumer should be aware that different -approaches may be used and should refer to the autoloader documentation. +1. Preceding Namespace separators MUST be removed. -### 3.2. Registered Autoloaders +2. The "Namespace Prefix", when present, of a "Fully Qualified Class Name" + MUST be replaced with the "Base Location" related to that "Namespace + Prefix". If the "Namespace Prefix" is empty, then the "Base Location" + is prepended to the "Fully Qualified Class Name" -1. A relationship MUST be present between a "namespace prefix" and the "base -directory". This relationship allows a registered autoloader to know where to -identify the location of the class. To establish this relationship, the -registered autoloader MUST transform the "fully qualified class name" into a -"mapped file name" as follows: +3. All Namespace separators MUST be replaced with the separators for the + respective location scheme; in case of physical files this means that the + directory separators for the respective operating system MUST be used. - 1.1. The "namespace prefix" portion of the "fully qualified class name" - MUST be replaced with the corresponding "base directory". +4. The result from the above rules MUST be suffixed with the string `.php`. - 1.2. Namespace separators in the "relative class name" portion of the - "fully qualified class name" MUST be replaced with directory separators - for the respective operating system. +If the "Mapped File Location" is readable then the application or library MUST +include or require it. - 1.3. The result MUST be suffixed with `.php`. +For example: -2. If the "mapped file name" exists in the file system, the registered -autoloader MUST include or require it. + Given the "Fully Qualified Class Name" of + `\Acme\Log\Formatter\LineFormatter`, the Namespace Prefix `Acme\Log\` and + the "Base Location" `./src/` the following will happen: -3. The registered autoloader MUST NOT throw exceptions, MUST NOT raise errors -of any level, and SHOULD NOT return a value. + 1. `\Acme\Log\Formatter\LineFormatter` becomes + `Acme\Log\Formatter\LineFormatter`. + 2. `Acme\Log\Formatter\LineFormatter` is changed into + `./src/Formatter\LineFormatter`. + 3. The directory separators for `./src/Formatter\LineFormatter` are + replaced and the whole becomes `./src/Formatter/LineFormatter`. + 4. Lastly the `.php` extension is added so that the "Mapped File Location" + will become `./src/Formatter/LineFormatter.php`. +A "Namespace Prefix" MAY have a relationship with more than one "Base +Location". When applicable, the application or library attempting to locate +a File Resource Location must search every "Base Location" until a readable +"Mapped File Location" is encountered. -4. Implementations ------------------- +The order in which an application will attempt to map a "Class" to +one of those locations is not within the scope of this specification. +Developers should be aware that different approaches MAY be used and SHOULD +refer to the documentation of the application with which they map "Classes" +to locations. -For example implementations, please see the [examples file][]. Example -implementations MUST NOT be regarded as part of the specification. They are -examples only, and MAY change at any time. +To prevent clashes and confusion with developers different "Namespace Prefixes" +SHOULD NOT map onto the same "Base Location". -[examples]: psr-4-autoloader-examples.php +An application or library MUST NOT throw exceptions or raise errors (of any +level) during the translation process. This will ensure that the process of +sequentially loading "Classes" is not abruptly stopped partway. From 0e75d8a9f83d206c011728960d579371f249221b Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Fri, 11 Oct 2013 21:12:49 +0200 Subject: [PATCH 18/64] Change indentation to MD format --- proposed/psr-4-autoloader/psr-4-autoloader.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/proposed/psr-4-autoloader/psr-4-autoloader.md b/proposed/psr-4-autoloader/psr-4-autoloader.md index f29b48067..dd0b4238c 100644 --- a/proposed/psr-4-autoloader/psr-4-autoloader.md +++ b/proposed/psr-4-autoloader/psr-4-autoloader.md @@ -64,9 +64,9 @@ rules in PSR-0. Example: - Given a "Fully Qualified Class Name" of - `Acme\Log\Formatter\LineFormatter`, the "Namespace Prefix" could be - `Acme\`, `Acme\Log\`, or `Acme\Log\Formatter\`. + > Given a "Fully Qualified Class Name" of + > `Acme\Log\Formatter\LineFormatter`, the "Namespace Prefix" could be + > `Acme\`, `Acme\Log\`, or `Acme\Log\Formatter\`. A "Namespace Prefix" MUST NOT include a leading namespace separator, but MUST include a trailing namespace separator. @@ -81,16 +81,16 @@ rules in PSR-0. For example: - A "Base Location" can be the folder `./src/`; in which case attempting - to locate the "Fully Qualified Class Name" - `Acme\Log\Formatter\LineFormatter` will result in the File Resource - Location `./src/Acme/Log/Formatter/LineFormatter.php`. - - Should the "Base Location" `./src/` be related to the "Namespace - Prefix" `Acme\Log` then the File Resource Location would become - `./src/Formatter/LineFormatter.php`. - - See chapter 4 for more information on the translation process. + > A "Base Location" can be the folder `./src/`; in which case attempting + > to locate the "Fully Qualified Class Name" + > `Acme\Log\Formatter\LineFormatter` will result in the File Resource + > Location `./src/Acme/Log/Formatter/LineFormatter.php`. + > + > Should the "Base Location" `./src/` be related to the "Namespace + > Prefix" `Acme\Log` then the File Resource Location would become + > `./src/Formatter/LineFormatter.php`. + > + > See chapter 4 for more information on the translation process. The "Base Location" MUST include a trailing separator applicable to the respective location scheme; in case of physical files this means the @@ -127,8 +127,8 @@ namespace to a File Resource Location. For example: - With a "Fully Qualified Class Name" of `Acme\Log\Baz`, the - "Namespace Parts" are `Acme\Log` and the "Class" name is `Baz`. + > With a "Fully Qualified Class Name" of `Acme\Log\Baz`, the + > "Namespace Parts" are `Acme\Log` and the "Class" name is `Baz`. 2. The first "Namespace Part" of a namespace or "Fully Qualified Class Name" MUST be a vendor name unique to the developer. This will prevent clashes @@ -137,13 +137,13 @@ namespace to a File Resource Location. It is RECOMMENDED for the second "Namespace Part" to be a unique name describing the application or library but this is not required. - An example of this concept is: + An example of this concept is: - `\Vendor\ClassName` + > `\Vendor\ClassName` - or when the application name is used as second "Namespace Part": + or when the application name is used as second "Namespace Part": - `\Vendor\Application\ClassName` + > `\Vendor\Application\ClassName` 3. This specification does not impose a limit on the number of "Namespace Parts" used by the developer of an application or library. It is @@ -183,18 +183,18 @@ include or require it. For example: - Given the "Fully Qualified Class Name" of - `\Acme\Log\Formatter\LineFormatter`, the Namespace Prefix `Acme\Log\` and - the "Base Location" `./src/` the following will happen: - - 1. `\Acme\Log\Formatter\LineFormatter` becomes - `Acme\Log\Formatter\LineFormatter`. - 2. `Acme\Log\Formatter\LineFormatter` is changed into - `./src/Formatter\LineFormatter`. - 3. The directory separators for `./src/Formatter\LineFormatter` are - replaced and the whole becomes `./src/Formatter/LineFormatter`. - 4. Lastly the `.php` extension is added so that the "Mapped File Location" - will become `./src/Formatter/LineFormatter.php`. +> Given the "Fully Qualified Class Name" of +> `\Acme\Log\Formatter\LineFormatter`, the Namespace Prefix `Acme\Log\` and +> the "Base Location" `./src/` the following will happen: +> +> 1. `\Acme\Log\Formatter\LineFormatter` becomes +> `Acme\Log\Formatter\LineFormatter`. +> 2. `Acme\Log\Formatter\LineFormatter` is changed into +> `./src/Formatter\LineFormatter`. +> 3. The directory separators for `./src/Formatter\LineFormatter` are +> replaced and the whole becomes `./src/Formatter/LineFormatter`. +> 4. Lastly the `.php` extension is added so that the "Mapped File Location" +> will become `./src/Formatter/LineFormatter.php`. A "Namespace Prefix" MAY have a relationship with more than one "Base Location". When applicable, the application or library attempting to locate From b26791d531beaa3d28848b67ea6ed082aa653743 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Fri, 11 Oct 2013 21:31:57 +0200 Subject: [PATCH 19/64] Fix numbering --- proposed/psr-4-autoloader/psr-4-autoloader.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposed/psr-4-autoloader/psr-4-autoloader.md b/proposed/psr-4-autoloader/psr-4-autoloader.md index dd0b4238c..02790b8ab 100644 --- a/proposed/psr-4-autoloader/psr-4-autoloader.md +++ b/proposed/psr-4-autoloader/psr-4-autoloader.md @@ -99,7 +99,7 @@ rules in PSR-0. - "Mapped File Location" is the end-product of the translation of a "Fully Qualified Class Name" and represents a File Resource Location. -3. Specification +5. Specification ---------------- For an application to be able to translate a "Fully Qualified Class Name" this @@ -120,7 +120,7 @@ to the way developers MUST deal with namespaces and "Fully Qualified Class Names", the subsequent chapter will describe the process of translating a namespace to a File Resource Location. -### 3.1. Principles +### 5.1. Principles 1. A "Fully Qualified Class Name" MUST begin with one or more "Namespace Parts" and MUST end with a "Class" name. @@ -152,7 +152,7 @@ namespace to a File Resource Location. 4. The File Location for a "Class" MUST match the capitalization of the "Class" and its "Namespace Parts". -### Translating a "Fully Qualified Class Name" into a File Resource location +### 5.2. Translating a "Fully Qualified Class Name" into a File Resource location A relationship MAY be present between a "Namespace Prefix" and a "Base Location". This relationship allows an application or library to locate a From 7b822dd2ffc2227d197a60031cdfaac9ac54261a Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Fri, 29 Nov 2013 23:52:46 +0100 Subject: [PATCH 20/64] Fixes #34: altered special exception for @return --- proposed/phpdoc.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 469444a4d..5ad3768ae 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1301,12 +1301,11 @@ 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: +It is RECOMMENDED to use this tag with every function and method. An exception to +this recommendation, as defined by the Coding Standard of any individual project, +MAY be: -1. **constructors**: the @return tag MAY be omitted here, in which case an - interpreter MUST interpret this as if `@return $this` is provided. -2. **functions and methods without a `return` value**: the @return tag MAY be + **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. From c54bc1fa2c125905200cb0ef32f6a5ece58bf3d9 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 30 Nov 2013 00:02:53 +0100 Subject: [PATCH 21/64] #36 Addresses an ambiguous example --- proposed/phpdoc.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 5ad3768ae..a9fb9b0d9 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -134,21 +134,21 @@ interpreted as described in [RFC 2119][RFC2119]. */ class Foo { - /** @type string|null $description Should contain a description */ - protected $description = null; + /** @type string|null $title contains a title for the Foo with a max. length of 24 characters */ + protected $title = null; /** - * This method sets a description. + * Sets a single-line title. * - * @param string $description A text with a maximum of 80 characters. + * @param string $title A text with a maximum of 24 characters. * * @return void */ - public function setDescription($description) + public function setTitle($title) { // there should be no docblock here - $this->description = $description; + $this->title = $title; } } ``` From 365d1a121b8aed4502755ad7755eba4d9165a19e Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 21:54:50 +0100 Subject: [PATCH 22/64] Removed meta-information as that is already, or should be, in the meta-doc --- proposed/phpdoc.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index a9fb9b0d9..a7defbec6 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1,20 +1,6 @@ PSR-5: PHPDoc ============= -Author(s): - - Mike van Riel (@mvriel) - -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 @@ -1301,8 +1287,8 @@ 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. An exception to -this recommendation, as defined by the Coding Standard of any individual project, +It is RECOMMENDED to use this tag with every function and method. An exception to +this recommendation, as defined by the Coding Standard of any individual project, MAY be: **functions and methods without a `return` value**: the @return tag MAY be From 1d6b650e05dab96683efe0731ae2a46306d6f69b Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 21:56:17 +0100 Subject: [PATCH 23/64] Removed erroneous TOC entry --- proposed/phpdoc.md | 1 - 1 file changed, 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index a7defbec6..cfc310c3b 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -20,7 +20,6 @@ PSR-5: PHPDoc 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 From eac8337a024ab849993670e266dbef49a02d08a7 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 22:06:57 +0100 Subject: [PATCH 24/64] Refactored the @type definition according to recent discussions --- proposed/phpdoc.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index cfc310c3b..e88394ad0 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1533,7 +1533,7 @@ function count() You may use the @type tag to document the "Type" of the following "Structural Elements": -* Constants, both class and global +* Constants, both class and global scope * Properties * Variables, both global and local scope @@ -1543,21 +1543,20 @@ You may use the @type tag to document the "Type" of the following #### 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. +The @type tag defines which type of data is represented by a value of 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. +Each Constant or Property definition or Variable where the type is ambiguous +or unknown SHOULD be preceded by a DocBlock containing the @type tag. Any +other variable MAY be preceded with a DocBlock containing the @type tag. -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. +The @type tag MUST contain the name of the element it documents. An exception +to this is when property declarations only refer to a single property. In this +case the name of the property MAY be omitted. -It is NOT RECOMMENDED to use the @var alias unless it is necessary in order for -the application, or associated tools, to function correctly. +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. #### Examples @@ -1574,7 +1573,7 @@ Or: ```php class Foo { - /** @type string|null $description Should contain a description */ + /** @type string|null Should contain a description */ protected $description = null; public function setDescription($description) From 78c73ecc10ecfd7f781df296173de46370f23b0f Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 22:49:15 +0100 Subject: [PATCH 25/64] #36 Adjusted ABNF to allows line breaks in tag descriptions --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e88394ad0..f03cae5ad 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -278,7 +278,7 @@ definition: 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-description = 1*(CHAR / CRLF) tag-signature = "(" *tag-argument ")" tag-argument = *SP 1*CHAR [","] *SP From 0f90737865cbcf90d9810ff5c7e17646ebbb29aa Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 22:58:28 +0100 Subject: [PATCH 26/64] #36 Clarified the structure of a tag by describing the parts and that a tag should start on a newline --- proposed/phpdoc.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index f03cae5ad..b86550366 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -322,10 +322,22 @@ Common uses for the long description are (amongst others): ### 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. +succeeding "Structural Element". Each tag starts on a new line, followed +by an at-sign (@) and a tag-name followed by white-space and meta-data +(including a description) or Inline PHPDoc. + +If meta-data is provided, it MAY span multiple lines and COULD follow a +strict format, and as such provide parameters, as dictated by the type of tag. +The type of the tag can be derived from its name. + +For example: + +> `@param string $argument1 This is a parameter.` +> +> The above tag consists of a name ('param') and meta-data +> ('string $argument1 This is a parameter.') where the meta-data is split into a +> "Type" ('string'), variable name ('$argument') and description +> ('This is a parameter.'). 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 @@ -353,6 +365,7 @@ 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. From 2e1b5059a2f9d36b16ea9229c671c1cb1b001d49 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 23:10:42 +0100 Subject: [PATCH 27/64] Fix typo --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index b86550366..3d310c2b9 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1068,7 +1068,7 @@ function count() } /** - * This method counts the occurences of Foo. + * This method counts the occurrences 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. From 520e4106f95b253d34883faa3e3614077e1ebb9b Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 23:11:59 +0100 Subject: [PATCH 28/64] Clarify that @var is not as much an alias of @type --- proposed/phpdoc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 3d310c2b9..bc553ade7 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1692,8 +1692,8 @@ function executeMyView() ### 8.24. @var [deprecated] -The @var tag is a **deprecated** alias for `@type`. Please see the documentation -for [@type](#822-type) for details of its usage. +The @var tag is **deprecated** in favor of `@type`. Please see the +documentation for [@type](#822-type) for details of its usage. ### 8.25. @version From 1df25826eebc7e8f54b3a13203c9b850f2a8beb5 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Dec 2013 23:16:19 +0100 Subject: [PATCH 29/64] #2 describe @see in more detail and add deprecation of @link --- proposed/phpdoc.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index bc553ade7..251087028 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1030,7 +1030,10 @@ and this SHOULD be interpreted as if having the URL mentioned in the registry. */ ``` -### 8.10. @link +### 8.10. @link [deprecated] + +*This tag is deprecated in favor of the `@see` tag, which since this +specification may relate to URIs.* The @link tag indicates a custom relation between the associated "Structural Element" and a website, which is identified by an absolute URI. @@ -1341,8 +1344,8 @@ a website or other "Structural Elements". #### Description -The @see tag can be used to define a reference to other -"Structural Elements" or to an URI. +The @see tag can be used to define a reference to other "Structural Elements" +or to a 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 @@ -1351,13 +1354,13 @@ 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?) +string wrapped in colons that defines the type of relation. The list of +supported relation types is not maintained in this document as is may +change over time. The meta document will contain a series of recommendation +but projects are free to choose their own relation types if applicable. -The @see tag SHOULD have a description appended to provide additional -information regarding the relationship between the 2 elements. +The @see tag SHOULD have a description to provide additional information +regarding the relationship between the element and its target. #### Examples From 065e65b3cdcd41d4929dc04dd743a4824a3d4a00 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 7 Dec 2013 21:58:00 +0100 Subject: [PATCH 30/64] Add markdown as requirement for tag descriptions --- proposed/phpdoc.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 251087028..045775215 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -339,9 +339,19 @@ For example: > "Type" ('string'), variable name ('$argument') and description > ('This is a parameter.'). -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". +The description of a tag MUST support Markdown as a formatting language. Due to +the nature of Markdown it is legal to start the description of the tag on the same +or the subsequent line and interpret it in the same way. + +So the following tags are identical:: + + /** + * @type string This is a description. + * @type string This is a + * description. + * @type string + * This is a description. + */ 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 @@ -350,6 +360,10 @@ 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. +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". + 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. From 44519fda50d75691bc1176a1366075fe56edfed0 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 7 Dec 2013 22:03:56 +0100 Subject: [PATCH 31/64] Add markdown as requirement for tag descriptions --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 045775215..d8f908b26 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -343,7 +343,7 @@ The description of a tag MUST support Markdown as a formatting language. Due to the nature of Markdown it is legal to start the description of the tag on the same or the subsequent line and interpret it in the same way. -So the following tags are identical:: +So the following tags are semantically identical: /** * @type string This is a description. From 8fe3d423326f7cf2d4247a59da0f077482dd2242 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 25 Mar 2014 07:32:25 +0100 Subject: [PATCH 32/64] Introduced Summary Previously this document referred to the Short and Long Description in a PHPDoc. These terms may become confusing and I have replaced all mentions of Short Description with Summary and Long Description with Description. This change will make it easier to communicate which section is referred. --- proposed/phpdoc.md | 107 +++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 56 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index d8f908b26..2cb2d4c57 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -8,8 +8,8 @@ PSR-5: PHPDoc 3. Definitions 4. Basic Principles 5. The PHPDoc Format - 5.1. Short Description - 5.2. Long Description + 5.1. Summary + 5.2. Description 5.3. Tags 5.3.1. Tag Name 5.3.2. Tag Signature @@ -268,10 +268,10 @@ interpreted as described in [RFC 2119][RFC2119]. The PHPDoc format has the following [ABNF][RFC5234] definition: - PHPDoc = [short-description] [long-description] [tags] + PHPDoc = [summary] [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 + summary = *CHAR ("." 1*CRLF / 2*CRLF) + description = 1*(CHAR / inline-tag) 1*CRLF ; any amount of characters ; with inline tags inside tags = *(tag 1*CRLF) inline-tag = "{" tag "}" @@ -284,36 +284,34 @@ definition: Examples of use are included in chapter 5.4. -### 5.1. Short Description +### 5.1. Summary -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 Summary MUST contain an abstract of the "Structural Element" defining the +purpose. It is RECOMMENDED for Summaries to span a single line or at most two +but not more than that. + +A Summary MUST end with either -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. +If a Description is provided, then it MUST be preceded by a Summary. Otherwise +the Description will be considered the Summary, until the end of the Summary +is reached. -### 5.2. Long Description +### 5.2. Description -The long description is OPTIONAL but SHOULD be included when the +The 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. +more complex operations, than can be described in the Summary alone. -Any application parsing the long description is RECOMMENDED to support the +Any application parsing the 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): +Common uses for the Description are (amongst others): -* To provide more detail than the short description on what this method does. +* To provide more detail than the Summary 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 @@ -340,8 +338,8 @@ For example: > ('This is a parameter.'). The description of a tag MUST support Markdown as a formatting language. Due to -the nature of Markdown it is legal to start the description of the tag on the same -or the subsequent line and interpret it in the same way. +the nature of Markdown it is legal to start the description of the tag on the +same or the subsequent line and interpret it in the same way. So the following tags are semantically identical: @@ -353,16 +351,16 @@ So the following tags are semantically identical: * This is a description. */ -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 +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 +If a tag signature is present then there MUST NOT be a description present in the same tag. -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". +The meta-data supplied by tags could result in a change of actual runtime +behavior of the succeeding "Structural Element", in which case the term +"Annotation" is commonly used instead of "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 @@ -401,9 +399,8 @@ is OPTIONAL): > 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. +> *Important*: Tools using the PHPDoc Standard 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: @@ -449,9 +446,9 @@ A complete example could look like the following example: ```php /** - * This is a short description. + * This is a Summary. * - * This is a long description. It may span multiple lines + * This is a Description. It may span multiple lines * or contain 'code' examples using the _Markdown_ markup * language. * @@ -470,11 +467,11 @@ function test($parameter1, $e) } ``` -It is also allowed to omit the long description: +It is also allowed to omit the Description: ```php /** - * This is a short description. + * This is a Summary. * * @see Markdown * @@ -495,7 +492,7 @@ encouraged as you are missing information on the parameters and return value): ```php /** - * This is a short description. + * This is a Summary. */ function test($parameter1, $parameter2) { @@ -514,9 +511,9 @@ 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. + * This is the summary for MyMagicMethod. * - * @param string $argument1 + * @param string $argument1 Description for argument 1. * * @return integer * } @@ -535,8 +532,8 @@ 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) +* [Summary](#51-summary) +* [Description](#52-description) * A specific subset of [tags](#53-tags) * [@version](#825-version) * [@author](#82-author) @@ -547,24 +544,24 @@ 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 +present in the Description. When present the parser MUST insert the +super-element's 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 +> Note: a special circumstance here would be when the Description must be +> overridden but the Summary 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. +> Summary and override the 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 if the Summary would be overridden and Description MAY +> appear overridden if the block of text contains a Summary ending > as defined in the ABNF. ### 6.1. Class Or Interface @@ -835,8 +832,7 @@ same 'PHPDoc' pointing to the new element. 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. +with which code from an example file can be shown inline with the Description. #### Syntax @@ -876,7 +872,7 @@ 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 +are shown in the 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 @@ -951,7 +947,7 @@ variable and a variable documented in the project. 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 +a description to insert a piece of text that is only applicable for the developers of this software. #### Syntax @@ -978,7 +974,7 @@ associated element unless the user has explicitly indicated that internal elemen 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, +description text inline to the 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. @@ -1063,8 +1059,7 @@ or inline #### 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. +"Structural Element", or part of the description when used inline, to an URI. The URI MUST be complete and welformed as specified in RFC 2396. From db15c21810a2d443115c94066fe8589bde6d82a9 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 25 Mar 2014 08:24:19 +0100 Subject: [PATCH 33/64] Fixes #3: Add Inline PHPDoc description --- proposed/phpdoc.md | 69 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 2cb2d4c57..97d888952 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -13,8 +13,8 @@ PSR-5: PHPDoc 5.3. Tags 5.3.1. Tag Name 5.3.2. Tag Signature - 5.3.3. Inline PHPDoc - 5.4. Examples + 5.4. Inline PHPDoc + 5.5. Examples 6. Inheritance 6.1. Class Or Interface 6.2. Function Or Method @@ -268,19 +268,20 @@ interpreted as described in [RFC 2119][RFC2119]. The PHPDoc format has the following [ABNF][RFC5234] definition: - PHPDoc = [summary] [description] [tags] - inline-phpdoc = "{" *SP PHPDoc *SP "}" - summary = *CHAR ("." 1*CRLF / 2*CRLF) - description = 1*(CHAR / inline-tag) 1*CRLF ; any amount of characters + PHPDoc = [summary] [description] [tags] + inline-phpdoc = "{" *SP PHPDoc *SP "}" + summary = *CHAR ("." 1*CRLF / 2*CRLF) + 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 / CRLF) - tag-signature = "(" *tag-argument ")" - tag-argument = *SP 1*CHAR [","] *SP + tags = *(tag 1*CRLF) + inline-tag = "{" tag "}" + tag = "@" tag-name [":" tag-specialization] [tag-details] + tag-name = (ALPHA / "\") *(ALPHA / DIGIT / "\" / "-" / "_") + tag-specialization = 1*(ALPHA / DIGIT / "-") + tag-details = *SP (SP tag-description / tag-signature / inline-phpdoc) + tag-description = 1*(CHAR / CRLF) + tag-signature = "(" *tag-argument ")" + tag-argument = *SP 1*CHAR [","] *SP Examples of use are included in chapter 5.4. @@ -423,21 +424,49 @@ 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 +### 5.4. 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 +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 +An example is the `@method` tag. This tag can 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. +An example of this is: -### 5.4. Examples +```php +/** + * @method integer MyMagicMethod(string $argument1) { + * This is the summary for MyMagicMethod. + * + * @param string $argument1 Description for argument 1. + * + * @return integer + * } + */ +class MyMagicClass +{ + ... +} +``` + +In this example is described how the `@method` tag for the Magic Method +`MyMagicMethod` has a complete PHPDoc definition associated with it. In this +definition all constraints, constructs and tags that apply to a normal usage of +PHPDoc also apply. + +The meaning of an "Inline PHPDoc" element differs based on the context in which +it is provided. In the example above the "Inline PHPDoc" provides a regular +PHPDoc definition as would precede a method. + +To prevent confusion regarding the function of "Inline PHPDoc" elements MUST +their usage be restricted to tags and locations that are documented. + +### 5.5. 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. From cbf58ef737654b3b3b2e68117aba81ddb5c448bb Mon Sep 17 00:00:00 2001 From: Chuck Burgess Date: Sat, 29 Mar 2014 14:43:58 -0500 Subject: [PATCH 34/64] consolidate the two FQSEN definitions; --- proposed/phpdoc.md | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 97d888952..1c4cf9df7 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -213,10 +213,6 @@ interpreted as described in [RFC 2119][RFC2119]. *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: @@ -229,30 +225,6 @@ interpreted as described in [RFC 2119][RFC2119]. 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 From ed9e86340247b1ad30046492be546eaed84af11a Mon Sep 17 00:00:00 2001 From: Chuck Burgess Date: Sat, 29 Mar 2014 14:46:43 -0500 Subject: [PATCH 35/64] 'annotation' is a defined term, so use 'name' here; --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 97d888952..d7d65bd4d 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -604,7 +604,7 @@ A class or interface SHOULD inherit the following deprecated tags if supplied: * [@subpackage](#819-subpackage-deprecated) -The @subpackage MUST NOT be inherited if the @package annotation of the +The @subpackage MUST NOT be inherited if the @package name of the super-class (or interface) is not the same as the @package of the child class (or interface). From a3dacae8818ee4ec49913e0c5a9126edc7311c9e Mon Sep 17 00:00:00 2001 From: sun Date: Sun, 18 May 2014 19:05:27 +0200 Subject: [PATCH 36/64] Change meaning of @deprecated version and add a second machine-readable version. --- proposed/phpdoc.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 97d888952..ef42fad0c 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -829,7 +829,7 @@ deprecated and are to be removed in a future version. #### Syntax - @deprecated [<"Semantic Version">] [] + @deprecated [<"Semantic Version"> [<"Semantic Version">]] [] #### Description @@ -837,12 +837,16 @@ 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 specify a version number denoting the version in which it +has been deprecated (similar to @since). + +The tag MAY specify a second version number in which it is scheduled for removal +and up till which it is guaranteed to be included in the software. Starting with +the given version it MAY be removed without further notice. + +It MAY provide an additional description stating why the associated element is +deprecated. -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. @@ -851,9 +855,15 @@ same 'PHPDoc' pointing to the new element. ```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. + * + * @deprecated 1.0.0 2.0.0 + * @see \New\Recommended::method() */ ``` From f001ebe31cc72f8300f7d8e950d75b68bdfa7ff8 Mon Sep 17 00:00:00 2001 From: sun Date: Tue, 20 May 2014 15:11:23 +0200 Subject: [PATCH 37/64] Specify @deprecated versions as a range, delimited by a colon. --- proposed/phpdoc.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index ef42fad0c..6feae4b10 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -829,7 +829,7 @@ deprecated and are to be removed in a future version. #### Syntax - @deprecated [<"Semantic Version"> [<"Semantic Version">]] [] + @deprecated [<"Semantic Version">][:<"Semantic Version">] [] #### Description @@ -837,12 +837,16 @@ 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. -It is RECOMMENDED to specify a version number denoting the version in which it -has been deprecated (similar to @since). +It is RECOMMENDED to specify a version number range to denote the version in +which it has been deprecated. This version MAY be followed by a colon and +immediately followed by the version in which it is scheduled for removal; i.e., +up till which it is guaranteed to be included in the software. -The tag MAY specify a second version number in which it is scheduled for removal -and up till which it is guaranteed to be included in the software. Starting with -the given version it MAY be removed without further notice. +The starting version MAY be omitted to only specify the ending version, prefixed +with a colon. + +If an ending version has been specified, the associated 'Structural elements' +MAY be removed without further notice in that version or a later version. It MAY provide an additional description stating why the associated element is deprecated. @@ -856,14 +860,16 @@ same 'PHPDoc' pointing to the new element. /** * @deprecated * + * @deprecated 1.0.0:2.0.0 + * @see \New\Recommended::method() + * * @deprecated 1.0.0 * + * @deprecated :2.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. - * - * @deprecated 1.0.0 2.0.0 - * @see \New\Recommended::method() */ ``` From 604e15c8f28c3de216dcce5edd943da1fc2d1894 Mon Sep 17 00:00:00 2001 From: sun Date: Sat, 24 May 2014 18:05:56 +0200 Subject: [PATCH 38/64] Revised @deprecated tag description using explicit 'starting version' and 'ending version' terminology. --- proposed/phpdoc.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 6feae4b10..da009eff8 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -837,22 +837,31 @@ 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. -It is RECOMMENDED to specify a version number range to denote the version in -which it has been deprecated. This version MAY be followed by a colon and -immediately followed by the version in which it is scheduled for removal; i.e., -up till which it is guaranteed to be included in the software. +This tag MAY specify up to two version numbers in the sense of a version number +range: -The starting version MAY be omitted to only specify the ending version, prefixed -with a colon. +The first version number, referred to as the 'starting version', denotes the +version in which the associated element has been deprecated. -If an ending version has been specified, the associated 'Structural elements' +The second version number, referred to as the 'ending version', denotes the +version in which the associated element is scheduled for removal; i.e., up till +which the associated element is guaranteed to be included in the software. + +It is RECOMMENDED to specify both a 'starting version' and an 'ending version'. +In this case, the two version numbers MUST be separated by a colon (`:`) without +white-space in between. + +The 'starting version' MAY be omitted. In this case, the 'ending version' MUST +be preceded by a colon. + +If an 'ending version' has been specified, the associated 'Structural elements' MAY be removed without further notice in that version or a later version. -It MAY provide an additional description stating why the associated element is -deprecated. +This tag MAY 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. +If the associated element is superseded by another it is RECOMMENDED to add a +@see tag in the same 'PHPDoc' pointing to the new element. #### Examples From 8e272d449fe4d68699a4e819e13aa344a142978a Mon Sep 17 00:00:00 2001 From: sun Date: Sat, 24 May 2014 20:32:42 +0200 Subject: [PATCH 39/64] Revised @deprecated to clarify that the stated 'ending version' is exclusive. --- proposed/phpdoc.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index da009eff8..c1cea3a5a 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -844,8 +844,11 @@ The first version number, referred to as the 'starting version', denotes the version in which the associated element has been deprecated. The second version number, referred to as the 'ending version', denotes the -version in which the associated element is scheduled for removal; i.e., up till -which the associated element is guaranteed to be included in the software. +version in which the associated element is scheduled for removal. + +If an 'ending version' has been specified, the associated 'Structural elements' +MAY no longer exist in the 'ending version' and MAY be removed without further +notice in that version or a later version, but MUST exist in all prior versions. It is RECOMMENDED to specify both a 'starting version' and an 'ending version'. In this case, the two version numbers MUST be separated by a colon (`:`) without @@ -854,9 +857,6 @@ white-space in between. The 'starting version' MAY be omitted. In this case, the 'ending version' MUST be preceded by a colon. -If an 'ending version' has been specified, the associated 'Structural elements' -MAY be removed without further notice in that version or a later version. - This tag MAY provide an additional description stating why the associated element is deprecated. From f9fccfa2f2e28998c620c2cb15f8e1e6495499c6 Mon Sep 17 00:00:00 2001 From: Christopher Hoult Date: Thu, 29 May 2014 15:01:09 +0100 Subject: [PATCH 40/64] Added description and some discussion on tag specializations --- proposed/phpdoc.md | 62 ++++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 22 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 1194b8f98..6bf1a2a77 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -12,7 +12,8 @@ PSR-5: PHPDoc 5.2. Description 5.3. Tags 5.3.1. Tag Name - 5.3.2. Tag Signature + 5.3.2. Tag Specialization + 5.3.3. Tag Signature 5.4. Inline PHPDoc 5.5. Examples 6. Inheritance @@ -259,8 +260,8 @@ Examples of use are included in chapter 5.4. ### 5.1. Summary -A Summary MUST contain an abstract of the "Structural Element" defining the -purpose. It is RECOMMENDED for Summaries to span a single line or at most two +A Summary MUST contain an abstract of the "Structural Element" defining the +purpose. It is RECOMMENDED for Summaries to span a single line or at most two but not more than that. A Summary MUST end with either @@ -268,8 +269,8 @@ A Summary MUST end with either * a full stop (.) followed by a line break * or two sequential line breaks. -If a Description is provided, then it MUST be preceded by a Summary. Otherwise -the Description will be considered the Summary, until the end of the Summary +If a Description is provided, then it MUST be preceded by a Summary. Otherwise +the Description will be considered the Summary, until the end of the Summary is reached. ### 5.2. Description @@ -311,7 +312,7 @@ For example: > ('This is a parameter.'). The description of a tag MUST support Markdown as a formatting language. Due to -the nature of Markdown it is legal to start the description of the tag on the +the nature of Markdown it is legal to start the description of the tag on the same or the subsequent line and interpret it in the same way. So the following tags are semantically identical: @@ -331,8 +332,8 @@ 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. -The meta-data supplied by tags could result in a change of actual runtime -behavior of the succeeding "Structural Element", in which case the term +The meta-data supplied by tags could result in a change of actual runtime +behavior of the succeeding "Structural Element", in which case the term "Annotation" is commonly used instead of "Tag". Annotations will not be described in further detail in this specification as @@ -384,7 +385,28 @@ Example of a tag name prefixed with a vendor name and hyphen: 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 +#### 5.3.2. Tag Specialization + +In order to provide a method by which to provide nuance to the tags defined in +this standard but without expanding the base set, a tag specialization MAY be +provided after the tag name by adding a colon followed by a string that provides +a more nuanced description of the tag. The list of supported tag specializations +is not maintained in this document as it may change over time. The meta document +will contain a series of recommendations on a per-tag name basis, but projects +are free to choose their own tag specializations if applicable. + +For example: + +> `@see:unit-test \Mapping\EntityTest::testGetId` +> +> The above tag consists of a name ('see') and tag specialization ('unit-test'), +> and thus defines a relation to the unit test for the proceeding method. + +> *Important*: Tools using the PHPDoc Standard MAY interpret tag specializations +> that are registered with that application and apply custom behaviour, but are +> only expected to implement the preceding tag name. + +#### 5.3.3. Tag Signature Tag signatures are commonly used for annotations to supply additional meta-data specific to the current tag. @@ -426,16 +448,16 @@ class MyMagicClass } ``` -In this example is described how the `@method` tag for the Magic Method +In this example is described how the `@method` tag for the Magic Method `MyMagicMethod` has a complete PHPDoc definition associated with it. In this -definition all constraints, constructs and tags that apply to a normal usage of +definition all constraints, constructs and tags that apply to a normal usage of PHPDoc also apply. The meaning of an "Inline PHPDoc" element differs based on the context in which -it is provided. In the example above the "Inline PHPDoc" provides a regular -PHPDoc definition as would precede a method. +it is provided. In the example above the "Inline PHPDoc" provides a regular +PHPDoc definition as would precede a method. -To prevent confusion regarding the function of "Inline PHPDoc" elements MUST +To prevent confusion regarding the function of "Inline PHPDoc" elements MUST their usage be restricted to tags and locations that are documented. ### 5.5. Examples @@ -1350,7 +1372,7 @@ a website or other "Structural Elements". #### Syntax - @see [URI | "FQSEN"] [<:type:>] [] + @see [URI | "FQSEN"] [] #### Description @@ -1363,14 +1385,10 @@ 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. The list of -supported relation types is not maintained in this document as is may -change over time. The meta document will contain a series of recommendation -but projects are free to choose their own relation types if applicable. - The @see tag SHOULD have a description to provide additional information -regarding the relationship between the element and its target. +regarding the relationship between the element and its target. Additionally, the +@see tag MAY have a tag specialization to add further definition to this +relationship. #### Examples From adc0241c41cfb8b7aed57545ff23d39e481fc6b6 Mon Sep 17 00:00:00 2001 From: Christopher Hoult Date: Thu, 29 May 2014 15:06:47 +0100 Subject: [PATCH 41/64] Improved layout of tag specialization docs --- proposed/phpdoc.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 6bf1a2a77..2fdb0dac4 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -395,6 +395,11 @@ is not maintained in this document as it may change over time. The meta document will contain a series of recommendations on a per-tag name basis, but projects are free to choose their own tag specializations if applicable. +*Important*: Tools using the PHPDoc Standard MAY interpret tag specializations +that are registered with/understood by that application and apply custom +behaviour, but are only expected to implement the preceding tag name as defined +in this standard. + For example: > `@see:unit-test \Mapping\EntityTest::testGetId` @@ -402,10 +407,6 @@ For example: > The above tag consists of a name ('see') and tag specialization ('unit-test'), > and thus defines a relation to the unit test for the proceeding method. -> *Important*: Tools using the PHPDoc Standard MAY interpret tag specializations -> that are registered with that application and apply custom behaviour, but are -> only expected to implement the preceding tag name. - #### 5.3.3. Tag Signature Tag signatures are commonly used for annotations to supply additional meta-data From 40f9b1358fac166dcafc0c9516d742bb2bed15e2 Mon Sep 17 00:00:00 2001 From: sun Date: Sat, 7 Jun 2014 01:01:11 +0200 Subject: [PATCH 42/64] Fixed synposis + description of `@license`. --- proposed/phpdoc.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 2fdb0dac4..d5b824215 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1037,29 +1037,39 @@ associated 'Structural Elements'. #### Syntax - @license [] [name] + @license <<"SPDX identifier">|> [label] #### 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. +The @license tag provides licensing information to the user, which is applicable +to 'Structural Elements' and 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 +The first parameter MUST be either a 'SPDX identifer', as defined by the +[SPDX Open Source License Registry][SPDX], or a URL to a document containing +the full license text. + +The second parameter MAY be the official name/label of the applicable license. + +It is RECOMMENDED to only specify a 'SPDX identifier', and to apply @license +tags to file-level 'PHPDoc' only, since multiple varying licences within a +single file may cause confusion with regard to which license applies at which time. -Whenever multiple licenses apply there MUST be one @license tag per applicable -license. +It is NOT RECOMMENDED to specify the @license tag in the 'PHPDoc' of every file +of a package, if the files are distributed as part of the package, and unless +the applied license requires to do so. -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. +In case multiple licenses apply, there MUST be one @license tag per applicable +license. #### Examples ```php /** * @license MIT + * + * @license GPL-2.0+ + * * @license http://www.spdx.org/licenses/MIT MIT License */ ``` From 1d07566e2727c0fffc9256e855977b875ace1b72 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 15 Jul 2014 18:11:15 +0200 Subject: [PATCH 43/64] Add typedef tag With this change we introduce a new tag called typedef. A powerful tag that allows you to define new types on the fly and augment existing types. --- proposed/phpdoc.md | 122 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 115 insertions(+), 7 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 97d888952..196b3cf8d 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -43,9 +43,10 @@ PSR-5: PHPDoc 8.20. @throws 8.21. @todo 8.22. @type - 8.23. @uses - 8.24. @var [deprecated] - 8.25. @version + 8.23. @typedef + 8.24. @uses + 8.25. @var [deprecated] + 8.26. @version Appendix A. Types Appendix B. Differences Compared With The De-facto PHPDoc Standard @@ -1678,7 +1679,114 @@ class Foo } ``` -### 8.23. @uses +### 8.23. @typedef + +Allows the author to define a custom type composed of one or more types that +may be augmented with key definitions, properties or methods. + +#### Syntax + + @typedef ["Type"] [<"QCN">] [<"Inline PHPDoc">] + +#### Description + +Using the `@typedef` tag it is possible to define a new pseudo-type or +associative array definition for use in PHPDoc blocks. + +Let's explain this concept by presenting the following use-cases: + +1. You want to document the properties of a class that is dynamically + constructed, such as the `\stdClass` coming from `json_decode`. +2. You have a configuration array for which you want to document its keys and + associated values. +3. You consume a library with magic methods who does not implement the `@method` + tag but still want to document which methods are on it yourself. +4. You want a pseudo-type called Scalar that represents either a string, float, + boolean or integer. +5. You have used class_alias() to create an alias and want PHPDoc to know which + class it is based from so that methods and properties could be inherited. + +The first parameter for the `@typedef` tag is the base "Type", +including compound types and collection classes, that is the defining "Type" +for the second parameter. The second parameter is used to name your pseudo-type, +and MUST be a Qualified Class Name. + +The second parameter MAY be omitted, in which case an "Inline PHPDoc" MUST be +defined. The information in the "Inline PHPDoc" will augment the existing base +class. Using this mechanism it is possible to provide additional information +with an existing class, such as methods or properties that could or were not +documented in the original. + +It is also possible to combine multiple "Types" into a single pseudo-type by +using the pipe operator (`|`), the examples section contains an example of use. + +##### Location + +A `@typedef` tag MUST always be placed on a DocBlock that belongs to a File or +Class. + +When associated with a File the type definition is considered to be +global and available throughout your project. It is NOT RECOMMENDED to use it +in this fashion without due consideration as you are making your documentation +harder to read without generator or IDE. + +Type definitions that are associated with a Class MUST only be used inside that +class, or its descendants, and are considered to have a visibility similar to +protected. + +##### Adding methods and properties on objects + +It is also possible to add new properties or methods using an "Inline PHPDoc", +and the `@property` and `@method` tags on any object. In this context an object +is any Qualified Class Name (QCN) that does not match one of PHP's primitive +types. A notable exception is the 'object' keyword, which may have methods and +properties added onto it. + +#### Examples + +##### Providing an alias for another class + +An example may be that the `\Storage` class is aliased using the +`class_alias()` function as `\Session`, and the elements of the `\Session` +class must be documented. + +The above can be accomplished with the following tag: + + @typedef \Storage \Session + +##### Defining additional elements on an aliased class + +Here is an example where we add a property and a summary on the new `\Session` +class. + +``` +@typedef \Storage \Session { + This class represents a session that stores user specific information. + + @property string $session_id +} +``` + +##### Combining multiple types into one + +An example of combining multiple types may be a class that is regularly +stubbed in unit tests: + + @typedef \Mockery\MockInterface|\My\DiContainer DicStub + +The above example will construct a pseudo-type DicStub that combines the methods +and properties of both the MockInterface and the DiContainer. + +##### Defining an associative array as pseudo-type + +``` +@typedef array \Configuration { + @type string $setting1 + @type string $setting2 +} +``` + +### 8.24. @uses Indicates whether the current "Structural Element" consumes the "Structural Element", or project file, that is provided as target. @@ -1689,7 +1797,7 @@ Indicates whether the current "Structural Element" consumes the #### Description -The @uses tag describes whether any part of the associated "Structural Element" +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. @@ -1731,12 +1839,12 @@ function executeMyView() } ``` -### 8.24. @var [deprecated] +### 8.25. @var [deprecated] The @var tag is **deprecated** in favor of `@type`. Please see the documentation for [@type](#822-type) for details of its usage. -### 8.25. @version +### 8.26. @version The @version tag is used to denote some description of "versioning" to an element. From 61c695c43d1b2c713acbfb3302f284c518421bc5 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Fri, 8 Aug 2014 13:37:38 +0200 Subject: [PATCH 44/64] Reverted @type to @var and changed compound @var notation to match PHPs During discussions is became obvious to me that the proposed rename of @var to @type encountered quite a bit of resistance and posed difficulties with existing annotation consumers, such as Doctrine, because they are using that namepart in their annotation names. In addition, due to a discussion at http://youtrack.jetbrains.com/issue/WI-7659, it become obvious that the notation where a DocBlock preceeds an individual property in a compound statement that it is picked up by PHP's Reflection library. As such I adapted the spec to match PHP's behaviour. You can reproduce this using the following script: getDocComment()); $reflectionProperty = new ReflectionProperty('A', 'c'); var_dump($reflectionProperty->getDocComment()); When you execute this you get the following output: string(25) "/** This is a DocBlock */" string(32) "/** This is a second DocBlock */" --- proposed/phpdoc.md | 256 ++++++++++++++++++++++----------------------- 1 file changed, 127 insertions(+), 129 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 196b3cf8d..d307d2f0d 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -42,11 +42,10 @@ PSR-5: PHPDoc 8.19. @subpackage [deprecated] 8.20. @throws 8.21. @todo - 8.22. @type - 8.23. @typedef - 8.24. @uses - 8.25. @var [deprecated] - 8.26. @version + 8.22. @typedef + 8.23. @uses + 8.24. @var + 8.25. @version Appendix A. Types Appendix B. Differences Compared With The De-facto PHPDoc Standard @@ -104,7 +103,7 @@ interpreted as described in [RFC 2119][RFC2119]. Example: ```php - /** @type int $int This is a counter. */ + /** @var int $int This is a counter. */ $int = 0; @@ -120,7 +119,7 @@ interpreted as described in [RFC 2119][RFC2119]. */ class Foo { - /** @type string|null $title contains a title for the Foo with a max. length of 24 characters */ + /** @var string|null $title contains a title for the Foo with a max. length of 24 characters */ protected $title = null; @@ -147,7 +146,7 @@ interpreted as described in [RFC 2119][RFC2119]. is not considered to be a "Structural Element" but a Control Flow statement. ```php - /** @type \Sqlite3 $sqlite */ + /** @var \Sqlite3 $sqlite */ foreach($connections as $sqlite) { // there should be no docblock here $sqlite->open('/my/database/path'); @@ -346,10 +345,10 @@ same or the subsequent line and interpret it in the same way. So the following tags are semantically identical: /** - * @type string This is a description. - * @type string This is a + * @var string This is a description. + * @var string This is a * description. - * @type string + * @var string * This is a description. */ @@ -532,7 +531,7 @@ function test($parameter1, $parameter2) A DocBlock may also span a single line as shown in the following example. ```php -/** @type \ArrayObject $array */ +/** @var \ArrayObject $array */ public $array = null; ``` @@ -647,23 +646,19 @@ root, a function or method in a class or interface MUST inherit the following ta 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](#822-type) - -A constant or property SHOULD inherit the following deprecated tags if supplied: - -* [@var](#824-var-deprecated) +* [@var](#822-type) ## 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' +@var, @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 +In either case each element of the hash is denoted with a @var 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 +Please note that the variable name part of the @var tag still needs to be preceded by a dollar sign for readability and parsability of the tag. Example: @@ -673,8 +668,8 @@ Example: * Initializes this class with the given options. * * @param array $options { - * @type boolean $required Whether this element is required - * @type string $label The display name for this element + * @var boolean $required Whether this element is required + * @var string $label The display name for this element * } */ public function __construct(array $options = array()) @@ -935,7 +930,7 @@ 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. +may not be superceded in part or in whole by the @var tag. The @global tag is used to denote a global variable or its usage. @@ -1091,7 +1086,7 @@ or inline The @link tag can be used to define a relation, or link, between the "Structural Element", or part of the description when used inline, to an URI. -The URI MUST be complete and welformed as specified in RFC 2396. +The URI MUST be complete and welformed as specified in [RFC 2396][RFC2396]. The @link tag MAY have a description appended to indicate the type of relation defined by this occurrence. @@ -1271,8 +1266,8 @@ an option array with 2 elements: 'required' and 'label'. * Initializes this class with the given options. * * @param array $options { - * @type boolean $required Whether this element is required - * @type string $label The display name for this element + * @var boolean $required Whether this element is required + * @var string $label The display name for this element * } */ public function __construct(array $options = array()) @@ -1583,103 +1578,7 @@ 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 scope -* Properties -* Variables, both global and local scope - -#### Syntax - - @type ["Type"] [element_name] [] - -#### Description - -The @type tag defines which type of data is represented by a value of a -Constant, Property or Variable. - -Each Constant or Property definition or Variable where the type is ambiguous -or unknown SHOULD be preceded by a DocBlock containing the @type tag. Any -other variable MAY be preceded with a DocBlock containing the @type tag. - -The @type tag MUST contain the name of the element it documents. An exception -to this is when property declarations only refer to a single property. In this -case the name of the property MAY be omitted. - -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. - -#### 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 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.23. @typedef +### 8.22. @typedef Allows the author to define a custom type composed of one or more types that may be augmented with key definitions, properties or methods. @@ -1781,12 +1680,12 @@ and properties of both the MockInterface and the DiContainer. ``` @typedef array \Configuration { - @type string $setting1 - @type string $setting2 + @var string $setting1 + @var string $setting2 } ``` -### 8.24. @uses +### 8.23. @uses Indicates whether the current "Structural Element" consumes the "Structural Element", or project file, that is provided as target. @@ -1839,10 +1738,109 @@ function executeMyView() } ``` -### 8.25. @var [deprecated] +### 8.24. @var + +You may use the @var tag to document the "Type" of the following +"Structural Elements": + +* Constants, both class and global scope +* Properties +* Variables, both global and local scope + +#### Syntax + + @var ["Type"] [element_name] [] + +#### Description + +The @var tag defines which type of data is represented by a value of a +Constant, Property or Variable. + +Each Constant or Property definition or Variable where the type is ambiguous +or unknown SHOULD be preceded by a DocBlock containing the @var tag. Any +other variable MAY be preceded with a DocBlock containing the @var tag. + +The @var tag MUST contain the name of the element it documents. An exception +to this is when property declarations only refer to a single property. In this +case the name of the property MAY be omitted. + +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. + +#### Examples + +```php +/** @var int $int This is a counter. */ +$int = 0; + +// there should be no docblock here +$int++; +``` + +Or: + +```php +class Foo +{ + /** @var string|null 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 +/** @var \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 +{ + protected + /** + * @var string Should contain a description + */ + $name, + /** + * @var string Should contain a description + */ + $description; -The @var tag is **deprecated** in favor of `@type`. Please see the -documentation for [@type](#822-type) for details of its usage. +} +``` + +Or constants: + +```php +class Foo +{ + const + /** + * @var string Should contain a description + */ + MY_CONST1 = "1", + /** + * @var string Should contain a description + */ + MY_CONST2 = "2"; + +} +``` ### 8.26. @version From a015038751687e9024196aa48ed7a008e5adf058 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Fri, 8 Aug 2014 19:07:12 +0200 Subject: [PATCH 45/64] Fixed chapter numbering --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index d307d2f0d..7b8ebf6e5 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1842,7 +1842,7 @@ class Foo } ``` -### 8.26. @version +### 8.25. @version The @version tag is used to denote some description of "versioning" to an element. From 1d20343b2e557c250736e872283b5a9ebdcd0853 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 16 Aug 2014 00:19:18 +0200 Subject: [PATCH 46/64] Added a text explaining how to recognize the File-level DocBlock --- proposed/phpdoc.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 2fdb0dac4..b2e702574 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -87,7 +87,7 @@ interpreted as described in [RFC 2119][RFC2119]. * "Structural Element" is a collection of Programming Constructs which SHOULD be preceded by a DocBlock. The collection contains the following constructs: - * namespace + * file * require(_once) * include(_once) * class @@ -234,7 +234,38 @@ interpreted as described in [RFC 2119][RFC2119]. * 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. + > placed at the top of a PHP source code file as the first DocBlock in a + > file. + > + > To prevent ambiguity when a Structural Element comes directly after a + > File-level DocBlock MUST such elements have their own DocBlock in + > addition to the File-level DocBlock. + > + > Example of a valid File-level DocBlock: + > + > ``` + > /** + > * This is a file-level DocBlock + > */ + > + > /** + > * This is a class DocBlock + > */ + > class MyClass { + > } + > ``` + > + > Example of an invalid File-level DocBlock + > + > ``` + > /** + > * This is a class DocBlock + > */ + > class MyClass { + > } + > ``` ## 5. The PHPDoc Format From 4f4b6407c4fce41c2728abe41e2cb6e4c7b2f348 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 16 Aug 2014 00:44:49 +0200 Subject: [PATCH 47/64] Clarified the paragraph on File-level DocBlocks --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index b2e702574..b0c8f412f 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -238,7 +238,7 @@ interpreted as described in [RFC 2119][RFC2119]. > file. > > To prevent ambiguity when a Structural Element comes directly after a - > File-level DocBlock MUST such elements have their own DocBlock in + > File-level DocBlock MUST that element have its own DocBlock in > addition to the File-level DocBlock. > > Example of a valid File-level DocBlock: From 8a6a2ffc431d24350eca1b228229a2509e51cc28 Mon Sep 17 00:00:00 2001 From: Richard Fussenegger Date: Sun, 23 Nov 2014 12:37:05 +0100 Subject: [PATCH 48/64] Clean-up of all external hyperlinks. * Link RFCs to the encrypted HTML version with extended functionality compared to the TXTs. * Link PHP Manual to the encrypted version which determines the user's language and do not use the `www.` prefix since this leads to a redirect. * The PHPDoc link to version 1.4 does not work, use latest instead since no other versions seem to work. * Trailing slash for domain (index path) * Link Wikipedia to the encrypted version. --- proposed/phpdoc.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index b0c8f412f..e88c00291 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -2070,16 +2070,16 @@ The following keywords are recognized by this PSR: This type is often used as return value for methods implementing the [Fluent Interface][FLUENT] design pattern. -[RFC2119]: http://www.ietf.org/rfc/rfc2119.txt -[RFC5234]: http://www.ietf.org/rfc/rfc5234.txt -[RFC2396]: http://www.ietf.org/rfc/rfc2396.txt +[RFC2119]: https://tools.ietf.org/html/rfc2119 +[RFC5234]: https://tools.ietf.org/html/rfc5234 +[RFC2396]: https://tools.ietf.org/html/rfc2396 [SEMVER2]: http://www.semver.org -[PHP_SUBSTR]: http://nl.php.net/manual/en/function.substr.php -[PHP_RESOURCE]: http://www.php.net/manual/en/language.types.resource.php -[PHP_PSEUDO]: http://php.net/manual/en/language.pseudo-types.php -[PHP_CALLABLE]: http://php.net/manual/en/language.types.callable.php -[SPDX]: http://www.spdx.org/licenses -[DEFACTO]: http://www.phpdoc.org/docs/1.4/index.html -[PHPDOC.ORG]: http://www.phpdoc.org -[FLUENT]: http://en.wikipedia.org/wiki/Fluent_interface -[COLLECTION]: http://en.wikipedia.org/wiki/Collection_(abstract_data_type) +[PHP_SUBSTR]: https://php.net/manual/function.substr.php +[PHP_RESOURCE]: https://php.net/manual/language.types.resource.php +[PHP_PSEUDO]: https://php.net/manual/language.pseudo-types.php +[PHP_CALLABLE]: https://php.net/manual/language.types.callable.php +[SPDX]: https://www.spdx.org/licenses +[DEFACTO]: http://www.phpdoc.org/docs/latest/index.html +[PHPDOC.ORG]: http://www.phpdoc.org/ +[FLUENT]: https://en.wikipedia.org/wiki/Fluent_interface +[COLLECTION]: https://en.wikipedia.org/wiki/Collection_(abstract_data_type) From ca1477e9c57bdd4700b534b2d7efb20afb173d5e Mon Sep 17 00:00:00 2001 From: Richard Fussenegger Date: Sun, 23 Nov 2014 12:45:51 +0100 Subject: [PATCH 49/64] Be more specific about static in PHPDoc vs. PHP This also fixes the *keyword* repetition. --- proposed/phpdoc.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e88c00291..b3c309f28 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -2059,8 +2059,8 @@ The following keywords are recognized by this PSR: which the documented element is contained, or when encountered in a subclass is of type of that subclass instead of the original class. - This keyword behaves the same way as the 'static' keyword keyword (not - the static property or method modifier) as defined by PHP. + This keyword behaves the same way as the [keyword for late static binding][PHP_OOP5LSB] + (not the static method, property, nor variable modifier) as defined by PHP. 15. '$this', the element to which this type applies is the same exact instance as the current Class in the given context. As such this type is a stricter @@ -2078,6 +2078,7 @@ The following keywords are recognized by this PSR: [PHP_RESOURCE]: https://php.net/manual/language.types.resource.php [PHP_PSEUDO]: https://php.net/manual/language.pseudo-types.php [PHP_CALLABLE]: https://php.net/manual/language.types.callable.php +[PHP_OOP5LSB]: https://php.net/manual/language.oop5.late-static-bindings.php [SPDX]: https://www.spdx.org/licenses [DEFACTO]: http://www.phpdoc.org/docs/latest/index.html [PHPDOC.ORG]: http://www.phpdoc.org/ From 30fdbb2a3f77ea019fcd25d99b977e593828a7d7 Mon Sep 17 00:00:00 2001 From: Richard Fussenegger Date: Sun, 23 Nov 2014 14:09:06 +0100 Subject: [PATCH 50/64] Formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 120 character (soft) limit per line as the rest of the document. Enclosed all types and values in code markup to stress the point that they are referring to text within the actual PHP scripts. Changed all values to uppercase, as is the case in every PHP documentation. This was used inconsistent if your compare the section of type null against the section of type true and false. Use the same example paragraph headings for all examples and do not switch between “For Example” and “Example X”. Also made them bold so they stand out more. Use PHP syntax highlighting for all code examples. Removed switching first letter’s case within continuous text of the word class to be always lowercased (there is no apparent reason why one would write it uppercased in some situations and lowercased in others). Made each reference to C() (the method from the self example) lowercased, since methods SHOULD always start with a lowercased letter, and removed the parentheses. Made each reference to A, B, and c italic/emphasized. --- proposed/phpdoc.md | 225 +++++++++++++++++++++------------------------ 1 file changed, 104 insertions(+), 121 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index b3c309f28..f0086f050 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1907,168 +1907,151 @@ or an instance of a class that is a (sub-)child to the given class. ### Keyword -A keyword defining the purpose of this type. Not every element is determined -by a class but still worthy of classification to assist the developer in -understanding the code covered by the DocBlock. +A keyword defining the purpose of this type. Not every element is determined by a class but still worthy of +classification to assist the developer in understanding the code covered by the DocBlock. -> Note: most of these keywords are allowed as class names in PHP and as -> such are hard to distinguish from real classes. As such the keywords MUST -> be lowercase, as most class names start with an uppercase first character, -> and you SHOULD NOT use classes with these names in your code. +**Note:** +> Most of these keywords are allowed as class names in PHP and as such are hard to distinguish from real classes. As +> such the keywords MUST be lowercase, as most class names start with an uppercase first character, and you SHOULD NOT +> use classes with these names in your code. -> There are more reasons to not name classes with the names of these -> keywords but that falls beyond the scope of this specification. +> There are more reasons to not name classes with the names of these keywords but that falls beyond the scope of this +> specification. The following keywords are recognized by this PSR: -1. 'string', the element to which this type applies is a string of - binary characters. +1. `string`, the element to which this type applies is a string of binary characters. -2. 'integer' or 'int', the element to which this type applies is a whole - number or integer. +2. `integer` or `int`, the element to which this type applies is a whole number or integer. -3. 'boolean' or 'bool', the element to which this type applies only has - state true or false. +3. `boolean` or `bool`, the element to which this type applies only has state `TRUE` or `FALSE`. -4. 'float' or 'double', the element to which this type applies is a continuous, - or real, number. +4. `float` or `double`, the element to which this type applies is a continuous, or real, number. -5. 'object', the element to which this type applies is the instance of an - undetermined class. +5. `object`, the element to which this type applies is the instance of an undetermined class. -6. 'mixed', the element to which this type applies can be of any type as - specified here. It is not known on compile time which type will be used. +6. `mixed`, the element to which this type applies can be of any type as specified here. It is not known on compile + time which type will be used. -7. 'array', the element to which this type applies is an array of values. +7. `array`, the element to which this type applies is an array of values. -8. 'resource', the element to which this type applies is a resource per - the [definition of PHP][PHP_RESOURCE]. +8. `resource`, the element to which this type applies is a resource per the [definition of PHP][PHP_RESOURCE]. -9. 'void', this type is commonly only used when defining the return type of a - method or function. - The basic definition is that the element indicated with this type does not - contain a value and the user should not rely on any retrieved value. +9. `void`, this type is commonly only used when defining the return type of a method or function. - For example: + The basic definition is that the element indicated with this type does not contain a value and the user should not + rely on any retrieved value. - /** - * @return void - */ - function outputHello() - { - echo 'Hello world'; - } - - In the example above no return statement is specified and thus the return - value is not determined. + **Example 1:** + ```php + /** + * @return void + */ + function outputHello() + { + echo 'Hello world'; + } + ``` - Example 2: + In the example above no return statement is specified and thus the return value is not determined. - /** - * @param boolean $hi when true 'Hello world' is echo-ed. - * - * @return void - */ - function outputHello($quiet) - { - if ($quiet} { - return; - } - echo 'Hello world'; + **Example 2:** + ```php + /** + * @param boolean $hi when true 'Hello world' is echo-ed. + * + * @return void + */ + function outputHello($quiet) + { + if ($quiet} { + return; } + echo 'Hello world'; + } + ``` - In this example the function contains a return statement without a given - value. Because there is no actual value specified, this also qualifies - as type 'void'. - -10. 'null', the element to which this type applies is a NULL value or, in - technical terms, does not exist. - - A big difference compared to void is that this type is used in any situation - where the described element may at any given time contain an explicit NULL - value. - - Example: + In this example the function contains a return statement without a given value. Because there is no actual value + specified, this also qualifies as type `void`. - /** - * @return null - */ - function foo() - { - echo 'Hello world'; - return null; - } +10. `null`, the element to which this type applies is a `NULL` value or, in technical terms, does not exist. - This type is commonly used in conjunction with another type to indicate that - it is possible that nothing is returned. + A big difference compared to `void` is that this type is used in any situation where the described element may at + any given time contain an explicit `NULL` value. - Example: + **Example 1:** + ```php + /** + * @return null + */ + function foo() + { + echo 'Hello world'; + return null; + } + ``` - /** - * @param boolean $create_new When true returns a new stdClass. - * - * @return stdClass|null - */ - function foo($create_new) - { - if ($create_new) { - return new stdClass(); - } + This type is commonly used in conjunction with another type to indicate that it is possible that nothing is + returned. - return null; + **Example 2:** + ```php + /** + * @param boolean $create_new When true returns a new stdClass. + * + * @return stdClass|null + */ + function foo($create_new) + { + if ($create_new) { + return new stdClass(); } + return null; + } + ``` -11. 'callable', the element to which this type applies is a pointer to a - function call. This may be any type of callable as defined in the PHP manual - about [pseudo-types][PHP_PSEUDO] or the section on [callable][PHP_CALLABLE]. +11. `callable`, the element to which this type applies is a pointer to a function call. This may be any type of callable + as defined in the PHP manual about [pseudo-types][PHP_PSEUDO] or the section on [callable][PHP_CALLABLE]. -12. 'false' or 'true', the element to which this type applies will have - the value true or false. No other value will be returned from this - element. +12. `false` or `true`, the element to which this type applies will have the value `TRUE` or `FALSE`. No other value will + be returned from this element. -13. 'self', the element to which this type applies is of the same Class as - which the documented element is originally contained. +13. `self`, the element to which this type applies is of the same class as which the documented element is originally + contained. - For example: + **Example:** - Method C() is contained in class A. The DocBlock states - that its return value is of type `self`. As such method C() - returns an instance of class A. + > Method *c* is contained in class *A*. The DocBlock states that its return value is of type `self`. As such method + > *c* returns an instance of class *A*. This may lead to confusing situations when inheritance is involved. - For example (previous example situation still applies): + **Example (previous example situation still applies):** - Class B extends Class A and does not redefine method C(). As such - it is possible to invoke method C() from class B. + > Class *B* extends class *A* and does not redefine method *c*. As such it is possible to invoke method *c* from + > class *B*. - In this situation ambiguity may arise as `self` could be interpreted as - either class A or B. In these cases `self` MUST be interpreted as being - an instance of the Class where the DocBlock containing the `self` type - is written. + In this situation ambiguity may arise as `self` could be interpreted as either class *A* or *B*. In these cases + `self` MUST be interpreted as being an instance of the class where the DocBlock containing the `self` type is + written. - In the examples above `self` MUST always refer to class A, since it is - defined with method C() in class A. + In the examples above `self` MUST always refer to class *A*, since it is defined with method *c* in class *A*. - > Due to the above nature it is RECOMMENDED for applications that - > collect and shape this information to show a list of child classes - > with each representation of the class. This would make it obvious - > for the user which classes are acceptable as type. + > Due to the above nature it is RECOMMENDED for applications that collect and shape this information to show a list + > of child classes with each representation of the class. This would make it obvious for the user which classes are + > acceptable as type. -14. 'static', the element to which this type applies is of the same Class as - which the documented element is contained, or when encountered in a - subclass is of type of that subclass instead of the original class. +14. `static`, the element to which this type applies is of the same class as which the documented element is contained, + or when encountered in a subclass is of type of that subclass instead of the original class. - This keyword behaves the same way as the [keyword for late static binding][PHP_OOP5LSB] - (not the static method, property, nor variable modifier) as defined by PHP. + This keyword behaves the same way as the [keyword for late static binding][PHP_OOP5LSB] (not the static method, + property, nor variable modifier) as defined by PHP. -15. '$this', the element to which this type applies is the same exact instance - as the current Class in the given context. As such this type is a stricter - version of 'static' as, in addition, the returned instance must not only - be of the same Class but also the same instance. +15. `$this`, the element to which this type applies is the same exact instance as the current class in the given + context. As such this type is a stricter version of `static` as, in addition, the returned instance must not only be + of the same class but also the same instance. - This type is often used as return value for methods implementing the - [Fluent Interface][FLUENT] design pattern. + This type is often used as return value for methods implementing the [Fluent Interface][FLUENT] design pattern. [RFC2119]: https://tools.ietf.org/html/rfc2119 [RFC5234]: https://tools.ietf.org/html/rfc5234 From 06336239aa72b9dbd2115dd23aad22aa0d6c9d0e Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 9 Dec 2014 21:52:58 +0100 Subject: [PATCH 51/64] Post-process @license edit --- proposed/phpdoc.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 1df33e890..9c8a5c82a 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1093,28 +1093,24 @@ associated 'Structural Elements'. #### Syntax - @license <<"SPDX identifier">|> [label] + @license [|URI] [name] #### Description The @license tag provides licensing information to the user, which is applicable to 'Structural Elements' and their child elements. -The first parameter MUST be either a 'SPDX identifer', as defined by the +The first parameter MUST be either a 'SPDX identifier', as defined by the [SPDX Open Source License Registry][SPDX], or a URL to a document containing the full license text. -The second parameter MAY be the official name/label of the applicable license. +The second parameter MAY be the official name of the applicable license. -It is RECOMMENDED to only specify a 'SPDX identifier', and to apply @license -tags to file-level 'PHPDoc' only, since multiple varying licences within a +It is RECOMMENDED to only specify an 'SPDX identifier' and to apply @license +tags to file-level 'PHPDoc' only, since multiple varying licenses within a single file may cause confusion with regard to which license applies at which time. -It is NOT RECOMMENDED to specify the @license tag in the 'PHPDoc' of every file -of a package, if the files are distributed as part of the package, and unless -the applied license requires to do so. - In case multiple licenses apply, there MUST be one @license tag per applicable license. From f650a1542f4dcf1b483b46966b8b0e92b11701b8 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Tue, 9 Dec 2014 23:15:58 +0100 Subject: [PATCH 52/64] Add paragraph with summary to clearly indicate no explicit recommendation for a markup language --- proposed/phpdoc.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 960e25c78..847814203 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -304,6 +304,12 @@ If a Description is provided, then it MUST be preceded by a Summary. Otherwise the Description will be considered the Summary, until the end of the Summary is reached. +Because a Summary is comparable to a chapter title it is beneficial to use as +little formatting as possible. As such, contrary to the Description (see next +chapter), no recommendation is done to support a mark-up language. It is +explicitly left up to the implementing application whether it wants to support +this or not. + ### 5.2. Description The Description is OPTIONAL but SHOULD be included when the From 6861e37b4e8d2bc34af980e2e9457ee68816515d Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 17 Dec 2014 18:57:34 +0100 Subject: [PATCH 53/64] #68: Add clause that an empty line is allowed between a DocBlock and element --- proposed/phpdoc.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 847814203..0a3f42df8 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -99,7 +99,8 @@ interpreted as described in [RFC 2119][RFC2119]. * 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. + definition and not with each usage. It is common practice to have the DocBlock + precede a Structural Element but it MAY also be separated by a an empty line. Example: From 46e4e4e776e5ba6a8277c4a16c125265a87dca21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Votruba?= Date: Thu, 19 Feb 2015 20:55:46 +0100 Subject: [PATCH 54/64] phpdoc.md - make TOC clickable --- proposed/phpdoc.md | 97 ++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 46 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 0a3f42df8..b05f967e3 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -3,52 +3,57 @@ PSR-5: PHPDoc ## Table Of Contents - 1. Introduction - 2. Conventions Used In This Document - 3. Definitions - 4. Basic Principles - 5. The PHPDoc Format - 5.1. Summary - 5.2. Description - 5.3. Tags - 5.3.1. Tag Name - 5.3.2. Tag Specialization - 5.3.3. Tag Signature - 5.4. Inline PHPDoc - 5.5. Examples - 6. Inheritance - 6.1. Class Or Interface - 6.2. Function Or Method - 6.3. Constant Or Property - 7. Describing hashes - 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. @typedef - 8.23. @uses - 8.24. @var - 8.25. @version - Appendix A. Types - Appendix B. Differences Compared With The De-facto PHPDoc Standard +- [1. Introduction](#1-introduction) +- [2. Conventions Used In This Document](#2-conventions-used-in-this-document) +- [3. Definitions](#3-definitions) +- [4. Basic Principles](#4-basic-principles) +- [5. The PHPDoc Format](#5-the-phpdoc-format) + - [5.1. Summary](#51-summary) + - [5.2. Description](#52-description) + - [5.3. Tags](#53-tags) + - [5.3.1. Tag Name](#531-tag-name) + - [5.3.2. Tag Specialization](#532-tag-specialization) + - [5.3.3. Tag Signature](#533-tag-signature) + - [5.4. Inline PHPDoc](#54-inline-phpdoc) + - [5.5. Examples](#55-examples) +- [6. Inheritance](#6-inheritance) + - [6.1. Class Or Interface](#61-class-or-interface) + - [6.2. Function Or Method](#62-function-or-method) + - [6.3. Constant Or Property](#63-constant-or-property) +- [7. Describing hashes](#7-describing-hashes) +- [8. Tags](#8-tags) + - [8.1. @api](#81-api) + - [8.2. @author](#82-author) + - [8.3. @category [deprecated]](#83-category-deprecated) + - [8.4. @copyright](#84-copyright) + - [8.5. @deprecated](#85-deprecated) + - [8.6. @example](#86-example) + - [8.7. @global](#87-global) + - [8.8. @internal](#88-internal) + - [8.9. @license](#89-license) + - [8.10. @link [deprecated]](#810-link-deprecated) + - [8.11. @method](#811-method) + - [8.12. @package](#812-package) + - [8.13. @param](#813-param) + - [8.14. @property](#814-property) + - [8.15. @return](#815-return) + - [8.16. @see](#816-see) + - [8.17. @since](#817-since) + - [8.18. @struct](#818-struct) + - [8.19. @subpackage [deprecated]](#819-subpackage-deprecated) + - [8.20. @throws](#820-throws) + - [8.21. @todo](#821-todo) + - [8.22. @typedef](#822-typedef) + - [8.23. @uses](#823-uses) + - [8.24. @var](#824-var) + - [8.25. @version](#825-version) +- [Appendix A. Types](#appendix-a-types) + - [ABFN](#abfn) + - [Details](#details) + - [Valid Class Name](#valid-class-name) + - [Keyword](#keyword) +- Appendix B. Differences Compared With The De-facto PHPDoc Standard + ## 1. Introduction From e287633ee7c57f84cec383f8b820e6e060b989eb Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Wed, 4 Mar 2015 20:31:47 +0100 Subject: [PATCH 55/64] Remove Style recommendation --- proposed/phpdoc.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index b05f967e3..f6d244cf5 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -2043,9 +2043,6 @@ A valid class name seen from the context where this type is mentioned. Thus this may be either a Fully Qualified Class Name (FQCN) or if present in a namespace a local name. -> It is RECOMMENDED for applications to expand any local name into a FQCN -> for easier processing and comparisons. - The element to which this type applies is either an instance of this class or an instance of a class that is a (sub-)child to the given class. From 0379e00bbedb23f526369032f0b9f1cdf02ccc92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nils=20R=C3=BCckmann?= Date: Fri, 6 Mar 2015 22:36:27 +0100 Subject: [PATCH 56/64] Fix small typo in @since example Even examples should follow the right syntax: @version ["Semantic Version"] [] --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index f6d244cf5..e7426696b 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1506,7 +1506,7 @@ The @since tag SHOULD NOT be used to show the current version of an element, the ```php /** * This is Foo - * @version MyApp 2.1.7 + * @version 2.1.7 MyApp * @since 2.0.0 introduced */ class Foo From 5f209f9dc94f80d6ebe7b6801a425f9cfa5d0fb2 Mon Sep 17 00:00:00 2001 From: Graham Campbell Date: Wed, 25 Mar 2015 12:12:54 +0000 Subject: [PATCH 57/64] Fixed scalar types --- proposed/phpdoc.md | 57 +++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index f6d244cf5..1c282b12d 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -478,12 +478,12 @@ An example of this is: ```php /** - * @method integer MyMagicMethod(string $argument1) { + * @method int MyMagicMethod(string $argument1) { * This is the summary for MyMagicMethod. * * @param string $argument1 Description for argument 1. * - * @return integer + * @return int * } */ class MyMagicClass @@ -577,12 +577,12 @@ Some tags may even feature an "Inline PHPDoc" as shown in the following example. ```php /** - * @method integer MyMagicMethod(string $argument1) { + * @method int MyMagicMethod(string $argument1) { * This is the summary for MyMagicMethod. * * @param string $argument1 Description for argument 1. * - * @return integer + * @return int * } */ class MyMagicClass @@ -706,8 +706,8 @@ Example: * Initializes this class with the given options. * * @param array $options { - * @var boolean $required Whether this element is required - * @var string $label The display name for this element + * @var bool $required Whether this element is required + * @var string $label The display name for this element * } */ public function __construct(array $options = array()) @@ -982,7 +982,7 @@ regards to the start and end limit. * * @example http://example.com/foo.phps * - * @return integer Indicates the number of items. + * @return int Indicates the number of items. */ function count() { @@ -1074,7 +1074,7 @@ Mark the count function as being internal to this project: /** * @internal * - * @return integer Indicates the number of items. + * @return int Indicates the number of items. */ function count() { @@ -1086,7 +1086,7 @@ function count() * * {@internal Silently adds one extra Foo to compensate for lack of Foo }} * - * @return integer Indicates the number of items. + * @return int Indicates the number of items. */ function count() { @@ -1166,7 +1166,7 @@ defined by this occurrence. /** * @link http://example.com/my/bar Documentation of Foo. * - * @return integer Indicates the number of items. + * @return int Indicates the number of items. */ function count() { @@ -1179,7 +1179,7 @@ function count() * 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. + * @return int Indicates the number of items. */ function count() { @@ -1228,8 +1228,8 @@ class Parent /** * @method string getString() - * @method void setInteger(integer $integer) - * @method setString(integer $integer) + * @method void setInteger(int $integer) + * @method setString(int $integer) */ class Child extends Parent { @@ -1335,8 +1335,8 @@ an option array with 2 elements: 'required' and 'label'. * Initializes this class with the given options. * * @param array $options { - * @var boolean $required Whether this element is required - * @var string $label The display name for this element + * @var bool $required Whether this element is required + * @var string $label The display name for this element * } */ public function __construct(array $options = array()) @@ -1420,7 +1420,7 @@ This tag MUST NOT occur more than once in a "DocBlock" and is limited to the ```php /** - * @return integer Indicates the number of items. + * @return int Indicates the number of items. */ function count() { @@ -1470,7 +1470,7 @@ relationship. * @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. + * @return int Indicates the number of items. */ function count() { @@ -1666,7 +1666,7 @@ Let's explain this concept by presenting the following use-cases: 3. You consume a library with magic methods who does not implement the `@method` tag but still want to document which methods are on it yourself. 4. You want a pseudo-type called Scalar that represents either a string, float, - boolean or integer. + bool or int. 5. You have used class_alias() to create an alias and want PHPDoc to know which class it is based from so that methods and properties could be inherited. @@ -1973,9 +1973,8 @@ A Type has the following [ABNF][RFC5234] definition: collection-type = class-name / "array" class-name = ["\"] label *("\" label) label = (ALPHA / %x7F-FF) *(ALPHA / DIGIT / %x7F-FF) - keyword = "array" / "bool" / "boolean" / "callable" / "double" / "false" / "float" / "int" / "integer" - keyword =/ "mixed" / "null" / "object" / "resource" / "self" / "static" / "string" / "true" / "void" - keyword =/ "$this" + keyword = "array" / "bool" / "callable" / "false" / "float" / "int" / "mixed" / "null" / "object" / + keyword = "resource" / "self" / "static" / "string" / "true" / "void" / "$this" ### Details @@ -2023,19 +2022,19 @@ Example: to indicate that this element returns an object of class ArrayObject th The type of the values in a Collection MAY be another array and even another Collection, - @return \ArrayObject<\ArrayObject> + @return \ArrayObject<\ArrayObject> A Collection MAY optionally define the type of the keys of said Collection by adding an additional type definition between the angular brackets before the identifier denoting the values' type. These two should be separated by a comma. Example: to declare an ArrayObject collection containing a list of strings with integer keys. - @return \ArrayObject + @return \ArrayObject The type of a value, or key, MAY consist of several different types, this can be represented by separating each individual type with a vertical bar sign between the angular brackets. - @return \ArrayObject + @return \ArrayObject ### Valid Class Name @@ -2068,11 +2067,11 @@ The following keywords are recognized by this PSR: 1. `string`, the element to which this type applies is a string of binary characters. -2. `integer` or `int`, the element to which this type applies is a whole number or integer. +2. `int`, the element to which this type applies is a whole number or integer. -3. `boolean` or `bool`, the element to which this type applies only has state `TRUE` or `FALSE`. +3. `bool`, the element to which this type applies only has state `TRUE` or `FALSE`. -4. `float` or `double`, the element to which this type applies is a continuous, or real, number. +4. `float`, the element to which this type applies is a continuous, or real, number. 5. `object`, the element to which this type applies is the instance of an undetermined class. @@ -2104,7 +2103,7 @@ The following keywords are recognized by this PSR: **Example 2:** ```php /** - * @param boolean $hi when true 'Hello world' is echo-ed. + * @param bool $hi when true 'Hello world' is echo-ed. * * @return void */ @@ -2143,7 +2142,7 @@ The following keywords are recognized by this PSR: **Example 2:** ```php /** - * @param boolean $create_new When true returns a new stdClass. + * @param bool $create_new When true returns a new stdClass. * * @return stdClass|null */ From 38222fec3523a229c7bbaf3853ec69f282d0dd85 Mon Sep 17 00:00:00 2001 From: Andrey Savchenko Date: Wed, 25 Mar 2015 19:32:04 +0200 Subject: [PATCH 58/64] "is it NOT" to "it is NOT" In two instances, both are statements, not questions. --- proposed/phpdoc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index f6d244cf5..8648eb520 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1253,8 +1253,8 @@ 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. +If, across the board, both logical and functional subdivisions are equal it +is 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 @@ -1549,7 +1549,7 @@ 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 +If, across the board, both logical and functional subdivisions are equal it is 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 From d6b9e48249d8d02668ac4354cc4e0f88c952cf3f Mon Sep 17 00:00:00 2001 From: Graham Campbell Date: Thu, 26 Mar 2015 10:28:09 +0000 Subject: [PATCH 59/64] Fixed an unclosed docblock --- proposed/phpdoc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 5ceb35073..10c332782 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -661,6 +661,7 @@ class Framework_ActionController /** * @package My * + */ class My_ActionController extends Framework_ActionController { <...> From eca33f8adec5be63495afb55c23a2a71cad12d85 Mon Sep 17 00:00:00 2001 From: Graham Campbell Date: Thu, 26 Mar 2015 10:28:43 +0000 Subject: [PATCH 60/64] Fixed a typo --- proposed/phpdoc.md | 1 - 1 file changed, 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 10c332782..81d690095 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -660,7 +660,6 @@ class Framework_ActionController /** * @package My - * */ class My_ActionController extends Framework_ActionController { From d486badfcb4c646cfcba507de13d61792b499a50 Mon Sep 17 00:00:00 2001 From: Wes Date: Sat, 2 May 2015 07:21:39 +0200 Subject: [PATCH 61/64] fix @version example fixing an example to be conforming to the allowed syntax @version [semantic-version] [description] --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 81d690095..15d1c6946 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1506,7 +1506,7 @@ The @since tag SHOULD NOT be used to show the current version of an element, the ```php /** * This is Foo - * @version MyApp 2.1.7 + * @version 2.1.7 MyApp * @since 2.0.0 introduced */ class Foo From 63af227573321f5af6cef4c2ab289294ed204d8d Mon Sep 17 00:00:00 2001 From: Gerard Roche Date: Mon, 20 Jul 2015 18:07:10 +0100 Subject: [PATCH 62/64] Update phpdoc.md --- proposed/phpdoc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index 81d690095..77d1d04a5 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -1306,7 +1306,7 @@ 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: +method. This tag MUST NOT occur more than once per parameter in a "PHPDoc" and is limited to "Structural Elements" of type method or function. @@ -1317,7 +1317,7 @@ limited to "Structural Elements" of type method or function. /** * Counts the number of items in the provided array. * - * @param mixed[] $array Array structure to count the elements of. + * @param mixed[] $items Array structure to count the elements of. * * @return int Returns the number of elements. */ @@ -1328,7 +1328,7 @@ 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'. +an option array with two elements: 'required' and 'label'. ```php /** From 3b425d167089e4c52c50c0828a3c5b34f94a1ad5 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Thu, 10 Dec 2015 06:20:25 +0100 Subject: [PATCH 63/64] Removed contentious sections and other various updates --- proposed/phpdoc.md | 425 ++++++++++++++++++--------------------------- 1 file changed, 170 insertions(+), 255 deletions(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index e41c2c46f..d8fcdad4b 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -17,36 +17,36 @@ PSR-5: PHPDoc - [5.4. Inline PHPDoc](#54-inline-phpdoc) - [5.5. Examples](#55-examples) - [6. Inheritance](#6-inheritance) - - [6.1. Class Or Interface](#61-class-or-interface) - - [6.2. Function Or Method](#62-function-or-method) - - [6.3. Constant Or Property](#63-constant-or-property) -- [7. Describing hashes](#7-describing-hashes) -- [8. Tags](#8-tags) - - [8.1. @api](#81-api) - - [8.2. @author](#82-author) - - [8.3. @category [deprecated]](#83-category-deprecated) - - [8.4. @copyright](#84-copyright) - - [8.5. @deprecated](#85-deprecated) - - [8.6. @example](#86-example) - - [8.7. @global](#87-global) - - [8.8. @internal](#88-internal) - - [8.9. @license](#89-license) - - [8.10. @link [deprecated]](#810-link-deprecated) - - [8.11. @method](#811-method) - - [8.12. @package](#812-package) - - [8.13. @param](#813-param) - - [8.14. @property](#814-property) - - [8.15. @return](#815-return) - - [8.16. @see](#816-see) - - [8.17. @since](#817-since) - - [8.18. @struct](#818-struct) - - [8.19. @subpackage [deprecated]](#819-subpackage-deprecated) - - [8.20. @throws](#820-throws) - - [8.21. @todo](#821-todo) - - [8.22. @typedef](#822-typedef) - - [8.23. @uses](#823-uses) - - [8.24. @var](#824-var) - - [8.25. @version](#825-version) + - [6.1. Making inheritance explicit using the @inheritDoc tag](#61-making-inheritance-explicit-using-the-inheritdoc-tag) + - [6.2. Using the {@inheritDoc} inline tag to augment a Description](#62-using-the-inheritdoc-inline-tag-to-augment-a-description) + - [6.3. Element-specific inherited parts] + - [6.3.1. Class Or Interface](#61-class-or-interface) + - [6.3.2. Function Or Method](#62-function-or-method) + - [6.3.3. Constant Or Property](#63-constant-or-property) +- [7. Tags](#7-tags) + - [7.1. @api](#71-api) + - [7.2. @author](#72-author) + - [7.3. @category [deprecated]](#73-category-deprecated) + - [7.4. @copyright](#74-copyright) + - [7.5. @deprecated](#75-deprecated) + - [7.6. @example](#76-example) + - [7.7. @global](#77-global) + - [7.8. @internal](#78-internal) + - [7.9. @license](#79-license) + - [7.10. @link [deprecated]](#710-link-deprecated) + - [7.11. @method](#711-method) + - [7.12. @package](#712-package) + - [7.13. @param](#713-param) + - [7.14. @property](#714-property) + - [7.15. @return](#715-return) + - [7.16. @see](#716-see) + - [7.17. @since](#717-since) + - [7.18. @subpackage [deprecated]](#719-subpackage-deprecated) + - [7.19. @throws](#720-throws) + - [7.20. @todo](#721-todo) + - [7.21. @uses](#723-uses) + - [7.22. @var](#724-var) + - [7.23. @version](#725-version) - [Appendix A. Types](#appendix-a-types) - [ABFN](#abfn) - [Details](#details) @@ -81,15 +81,15 @@ 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". +* "PHPDoc" is a section of documentation which provides information on aspects + of a "Structural Element". - > It is important to note that the PHPDoc and the DocBlock are two separate + > It is important to note that a PHPDoc and a 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. + > syntax as described in this specification such as the description and tags. -* "Structural Element" is a collection of Programming Constructs which SHOULD be +* "Structural Element" is a collection of Programming Constructs which MAY be preceded by a DocBlock. The collection contains the following constructs: * file @@ -103,9 +103,10 @@ interpreted as described in [RFC 2119][RFC2119]. * 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. It is common practice to have the DocBlock - precede a Structural Element but it MAY also be separated by a an empty line. + It is RECOMMENDED to precede a "Structural Element" with a DocBlock where it is + defined and not with each usage. It is common practice to have the DocBlock + precede a Structural Element but it MAY also be separated by a an undetermined + number of empty lines. Example: @@ -507,7 +508,7 @@ their usage be restricted to tags and locations that are documented. ### 5.5. 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. +advised to read through the list of tags in chapter 7. A complete example could look like the following example: @@ -593,54 +594,121 @@ 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). +A PHPDoc that is associated with a "Structural Element" that implements, extends +or overrides a "Structural Element" has the ability to inherit parts of +information from the PHPDoc associated with the "Structural Element" that is +implemented, extended or overridden. -Every "Structural Element" MUST inherit the following PHPDoc parts by default: +The PHPDoc for every type of "Structural Element" MUST inherit the following +parts if that part is absent: * [Summary](#51-summary) -* [Description](#52-description) -* A specific subset of [tags](#53-tags) - * [@version](#825-version) - * [@author](#82-author) - * [@copyright](#84-copyright) +* [Description](#52-description) and +* A specific subset of [tags](#53-tags): + * [@version](#725-version) + * [@author](#72-author) + * [@copyright](#74-copyright) + +The PHPDoc for each type of "Structural Element" MUST also inherit a +specialized subset of tags depending on which "Structural Element" is +associated. + +If a PHPDoc does not feature a part, such as Summary or Description, that is +present in the PHPDoc of a super-element, then that part is always implicitly +inherited. +The following is a list of all elements whose DocBlocks are able to inherit +information from a super-element's DocBlock: + +1. a Class' or Interface's DocBlock can inherit information from a Class or + Interface which it extends. +2. a Property's DocBlock can inherit information from a Property with the same + name that is declared in a superclass. +3. a Method's DocBlock can inherit information from a Method with the same + name that is declared in a superclass. +4. a Method's DocBlock can inherit information from a Method with the same + name that is declared in an implemented interface in the current Class + or that is implemented in a superclass. + +> For example: +> +> Let's assume you have a method `\SubClass::myMethod()` and its class +> `\SubClass` extends the class `\SuperClass`. And in the class `\SuperClass` +> there is a method with the same name (e.g. `\SuperClass::myMethod`). +> +> If the above applies then the DocBlock of `\SubClass::myMethod()` will +> inherit any of the parts mentioned above from the PHPDoc of +> `\SuperClass::myMethod`. So if the `@version` tag was not redefined then it +> is assumed that `\SubClass::myMethod()` will have the same `@version` +> tag. -Each specific "Structural Element" MUST also inherit a specialized subset as -defined in the sub-chapters. +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. -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 Description. When present the parser MUST insert the -super-element's Description at the location of the {@inheritdoc} inline -tag, while still including the current element's description. +## 6.1. Making inheritance explicit using the @inheritDoc tag -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. +Because inheritance is implicit it may happen that it is not necessary to +include a PHPDoc with a "Structural Element". This can cause confusion as it +is now ambiguous whether the PHPDoc was omitted on purpose or whether the +author of the code had forgotten to add documentation. -> Note: a special circumstance here would be when the Description must be -> overridden but the Summary 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 -> Summary and override the Description with the intended text. -> -> Without the {@inheritdoc} inline tag the reader MUST interpret any text -> as if the Summary would be overridden and Description MAY -> appear overridden if the block of text contains a Summary ending -> as defined in the ABNF. +In order to resolve this ambiguity the `@inheritDoc` tag can be used to +indicate that this element will inherit its information from a super-element. -### 6.1. Class Or Interface +Example: + + /** + * This is a summary. + */ + class SuperClass + { + } + + /** + * @inheritDoc + */ + class SubClass extends SuperClass + { + } + +In the example above the SubClass' Summary can be considered equal to that of +the SuperClass element, which is thus "This is a summary.". + +## 6.2. Using the {@inheritDoc} inline tag to augment a Description + +Sometimes you want to inherit the Description of a super-element and add your +own text with it to provide information specific to your "Structural Element". +This MUST be done using the `{@inheritDoc}` inline tag. + +The `{@inheritDoc}` inline tag will indicate that at that location the +super-element's description MUST be injected or inferred. + +Example: + + /** + * This is the Summary for this element. + * + * {@inheritDoc} + * + * In addition this description will contain more information that + * will provide a detailed piece of information specific to this + * element. + */ + +In the example above it is indicated that the Description of this PHPDoc is a +combination of the Description of the super-element, indicated by the +`{@inheritDoc}` inline tag, and the subsequent body text. + +### 6.3. 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](#812-package) +* [@package](#712-package) A class or interface SHOULD inherit the following deprecated tags if supplied: -* [@subpackage](#819-subpackage-deprecated) +* [@subpackage](#719-subpackage-deprecated) The @subpackage MUST NOT be inherited if the @package name of the super-class (or interface) is not the same as the @package of the child class @@ -670,69 +738,28 @@ class My_ActionController extends Framework_ActionController In the example above the My_ActionController MUST NOT inherit the subpackage _Controllers_. -### 6.2. Function Or Method +### 6.4. 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](#813-param) -* [@return](#815-return) -* [@throws](#820-throws) +* [@param](#713-param) +* [@return](#715-return) +* [@throws](#720-throws) -### 6.3. Constant Or Property +### 6.5. 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: -* [@var](#822-type) - -## 7. Describing hashes - -The structure of a hash may be described using an "Inline PHPDoc" as part of a -@var, @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 @var 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 @var tag still needs to be -preceded by a dollar sign for readability and parsability of the tag. - -Example: +* [@var](#722-type) -```php -/** - * Initializes this class with the given options. - * - * @param array $options { - * @var bool $required Whether this element is required - * @var 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 +## 7. Tags Unless specifically mentioned in the description each tag MAY occur zero or more times in each "DocBlock". -### 8.1. @api +### 7.1.. @api The @api tag is used to declare "Structural Elements" as being suitable for consumption by third parties. @@ -769,7 +796,7 @@ function showVersion() } ``` -### 8.2. @author +### 7.2. @author The @author tag is used to document the author of any "Structural Element". @@ -794,7 +821,7 @@ adhere to the syntax defined in RFC 2822. */ ``` -### 8.3. @category [deprecated] +### 7.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. @@ -829,7 +856,7 @@ This tag MUST NOT occur more than once in a "DocBlock". */ ``` -### 8.4. @copyright +### 7.4. @copyright The @copyright tag is used to document the copyright information of any "Structural element". @@ -856,7 +883,7 @@ covered by this copyright and the organization involved. */ ``` -### 8.5. @deprecated +### 7.5. @deprecated The @deprecated tag is used to indicate which 'Structural elements' are deprecated and are to be removed in a future version. @@ -916,7 +943,7 @@ If the associated element is superseded by another it is RECOMMENDED to add a */ ``` -### 8.6. @example +### 7.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 @@ -990,7 +1017,7 @@ function count() } ``` -### 8.7. @global +### 7.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 @var tag. @@ -1031,7 +1058,7 @@ variable and a variable documented in the project. (TODO: Examples for this tag should be added) -### 8.8. @internal +### 7.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 @@ -1094,7 +1121,7 @@ function count() } ``` -### 8.9. @license +### 7.9. @license The @license tag is used to indicate which license is applicable for the associated 'Structural Elements'. @@ -1134,7 +1161,7 @@ license. */ ``` -### 8.10. @link [deprecated] +### 7.10. @link [deprecated] *This tag is deprecated in favor of the `@see` tag, which since this specification may relate to URIs.* @@ -1187,7 +1214,7 @@ function count() } ``` -### 8.11. @method +### 7.11. @method The @method allows a class to know which 'magic' methods are callable. @@ -1237,7 +1264,7 @@ class Child extends Parent } ``` -### 8.12. @package +### 7.12. @package The @package tag is used to categorize "Structural Elements" into logical subdivisions. @@ -1286,7 +1313,7 @@ This tag MUST NOT occur more than once in a "DocBlock". */ ``` -### 8.13. @param +### 7.13. @param The @param tag is used to document a single parameter of a function or method. @@ -1345,7 +1372,7 @@ public function __construct(array $options = array()) } ``` -### 8.14. @property +### 7.14. @property The @property tag allows a class to know which 'magic' properties are present. @@ -1387,7 +1414,7 @@ class Child extends Parent } ``` -### 8.15. @return +### 7.15. @return The @return tag is used to document the return value of functions or methods. @@ -1436,7 +1463,7 @@ function getLabel() } ``` -### 8.16. @see +### 7.16. @see The @see tag indicates a reference from the associated "Structural Elements" to a website or other "Structural Elements". @@ -1478,7 +1505,7 @@ function count() } ``` -### 8.17. @since +### 7.17. @since The @since tag is used to denote _when_ an element was introduced or modified, using some description of "versioning" to that element. @@ -1528,12 +1555,7 @@ class Foo } ``` -### 8.18. @struct - -TODO: specify details -TODO: determine whether this is a correct approach - -### 8.19. @subpackage [deprecated] +### 7.18. @subpackage [deprecated] The @subpackage tag is used to categorize "Structural Elements" into logical subdivisions. @@ -1567,7 +1589,7 @@ DocBlock. */ ``` -### 8.20. @throws +### 7.19. @throws The @throws tag is used to indicate whether "Structural Elements" throw a specific type of exception. @@ -1611,7 +1633,7 @@ function count($items) } ``` -### 8.21. @todo +### 7.20. @todo The @todo tag is used to indicate whether any development activities should still be executed on associated "Structural Elements". @@ -1643,114 +1665,7 @@ function count() } ``` -### 8.22. @typedef - -Allows the author to define a custom type composed of one or more types that -may be augmented with key definitions, properties or methods. - -#### Syntax - - @typedef ["Type"] [<"QCN">] [<"Inline PHPDoc">] - -#### Description - -Using the `@typedef` tag it is possible to define a new pseudo-type or -associative array definition for use in PHPDoc blocks. - -Let's explain this concept by presenting the following use-cases: - -1. You want to document the properties of a class that is dynamically - constructed, such as the `\stdClass` coming from `json_decode`. -2. You have a configuration array for which you want to document its keys and - associated values. -3. You consume a library with magic methods who does not implement the `@method` - tag but still want to document which methods are on it yourself. -4. You want a pseudo-type called Scalar that represents either a string, float, - bool or int. -5. You have used class_alias() to create an alias and want PHPDoc to know which - class it is based from so that methods and properties could be inherited. - -The first parameter for the `@typedef` tag is the base "Type", -including compound types and collection classes, that is the defining "Type" -for the second parameter. The second parameter is used to name your pseudo-type, -and MUST be a Qualified Class Name. - -The second parameter MAY be omitted, in which case an "Inline PHPDoc" MUST be -defined. The information in the "Inline PHPDoc" will augment the existing base -class. Using this mechanism it is possible to provide additional information -with an existing class, such as methods or properties that could or were not -documented in the original. - -It is also possible to combine multiple "Types" into a single pseudo-type by -using the pipe operator (`|`), the examples section contains an example of use. - -##### Location - -A `@typedef` tag MUST always be placed on a DocBlock that belongs to a File or -Class. - -When associated with a File the type definition is considered to be -global and available throughout your project. It is NOT RECOMMENDED to use it -in this fashion without due consideration as you are making your documentation -harder to read without generator or IDE. - -Type definitions that are associated with a Class MUST only be used inside that -class, or its descendants, and are considered to have a visibility similar to -protected. - -##### Adding methods and properties on objects - -It is also possible to add new properties or methods using an "Inline PHPDoc", -and the `@property` and `@method` tags on any object. In this context an object -is any Qualified Class Name (QCN) that does not match one of PHP's primitive -types. A notable exception is the 'object' keyword, which may have methods and -properties added onto it. - -#### Examples - -##### Providing an alias for another class - -An example may be that the `\Storage` class is aliased using the -`class_alias()` function as `\Session`, and the elements of the `\Session` -class must be documented. - -The above can be accomplished with the following tag: - - @typedef \Storage \Session - -##### Defining additional elements on an aliased class - -Here is an example where we add a property and a summary on the new `\Session` -class. - -``` -@typedef \Storage \Session { - This class represents a session that stores user specific information. - - @property string $session_id -} -``` - -##### Combining multiple types into one - -An example of combining multiple types may be a class that is regularly -stubbed in unit tests: - - @typedef \Mockery\MockInterface|\My\DiContainer DicStub - -The above example will construct a pseudo-type DicStub that combines the methods -and properties of both the MockInterface and the DiContainer. - -##### Defining an associative array as pseudo-type - -``` -@typedef array \Configuration { - @var string $setting1 - @var string $setting2 -} -``` - -### 8.23. @uses +### 7.21. @uses Indicates whether the current "Structural Element" consumes the "Structural Element", or project file, that is provided as target. @@ -1803,7 +1718,7 @@ function executeMyView() } ``` -### 8.24. @var +### 7.22. @var You may use the @var tag to document the "Type" of the following "Structural Elements": @@ -1907,7 +1822,7 @@ class Foo } ``` -### 8.25. @version +### 7.23. @version The @version tag is used to denote some description of "versioning" to an element. From ead19fb5e48590e922a628be2691e9109236088d Mon Sep 17 00:00:00 2001 From: Michael Spiegel Date: Wed, 24 Feb 2016 13:32:55 +0100 Subject: [PATCH 64/64] Fix typo in table of contents Replace "ABFN" by "ABNF" --- proposed/phpdoc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/phpdoc.md b/proposed/phpdoc.md index d8fcdad4b..bdc47b431 100644 --- a/proposed/phpdoc.md +++ b/proposed/phpdoc.md @@ -48,7 +48,7 @@ PSR-5: PHPDoc - [7.22. @var](#724-var) - [7.23. @version](#725-version) - [Appendix A. Types](#appendix-a-types) - - [ABFN](#abfn) + - [ABNF](#abnf) - [Details](#details) - [Valid Class Name](#valid-class-name) - [Keyword](#keyword)