Inheritdoc php что это
The main purpose of this PSR is to provide a complete catalog of Tags in the PHPDoc standard.
This document SHALL NOT:
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.
See the Definitions section of the PHPDoc PSR, as those definitions apply here as well.
4. Regarding Inheritance
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.
The PHPDoc for every type of «Structural Element» MUST inherit the following parts if that part is absent:
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:
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.
4.1. Making inheritance explicit using the @inheritDoc tag
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.
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.
In the example above the SubClass’ Summary can be considered equal to that of the SuperClass element, which is thus «This is a summary.».
4.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.
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.
4.3. Element-specific inherited parts
4.3.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:
4.3.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:
4.3.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:
Unless specifically mentioned in the description each tag MAY occur zero or more times in each «DocBlock».
The @api tag is used to highlight «Structural Elements» as being part of the primary public API of a package.
The @api tag MAY be applied to public «Structural Elements» to highlight them in generated documentation, pointing the consumer to the primary public API components of a library or framework.
Other «Structural Elements» with a public visibility MAY be listed less prominently in generated documentation.
The @author tag is used to document the author of any «Structural Element».
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.
The @copyright tag is used to document the copyright information of any «Structural element».
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 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.
The @deprecated tag is used to indicate which ‘Structural elements’ are deprecated and are to be removed in a future version.
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, effective from the «Semantic Version» if provided.
This tag MAY provide an additional description stating why the associated element is deprecated.
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.
The @generated tag indicates that the code has been generated using an automation script.
The @generated is used to denote a class or a function that has been generated using an automation script. This tag should be used to warn to not change the code, since the change will be overwritten by the automation script.
Mark a class that has been generated using a PHP script.
Mark a function that has been generated using a PHP script.
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 description to insert a piece of text that is only applicable for the developers of this software.
Contrary to other inline tags, the inline version of this tag may also contain other inline tags (see second example below).
The @internal tag indicates that the associated «Structural Element» is intended only for use within the application, library or package to which it belongs.
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 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.
Mark the count function as being internal to this project:
Include a note in the Description that only Developer Docs would show.
The @link tag indicates a custom relation between the associated «Structural Element» and a website, which is identified by an absolute URI.
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 well-formed as specified in RFC 2396.
The @link tag MAY have a description appended to indicate the type of relation defined by this occurrence.
The @method allows a class to know which ‘magic’ methods are callable.
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 can ONLY be used in a PHPDoc that is associated with a class or interface.
The @package tag is used to categorize «Structural Elements» into logical subdivisions.
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 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 RECOMMENDED to keep the depth at less or equal than six levels.
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».
The @param tag is used to document a single parameter of a function or method.
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 «name» is required only when some @param tags are omitted due to all useful info already being visible in the code signature itself. The description is OPTIONAL yet RECOMMENDED.
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.
This tag MUST NOT occur more than once per parameter in a «PHPDoc» and is limited to «Structural Elements» of type method or function.
The @property tag is used to declare which «magic» properties are supported.
The @property tag is used when a class (or trait ) implements the __get() and/or __set() «magic» methods to resolve non-literal properties at run-time.
The @property-read and @property-write variants MAY be used to indicate «magic» properties that can only be read or written.
The @property tags can ONLY be used in a PHPDoc that is associated with a class or trait.
The @return tag is used to document the return value of functions or methods.
With the @return tag it is possible to document the return type of a function or method. When provided, it MUST contain a «Type» 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. 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 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.
The @see tag indicates a reference from the associated «Structural Elements» to a website or other «Structural Elements».
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 element (also called the «FQSEN»).
A URI MUST be complete and well-formed as specified in RFC 2396.
The @see tag SHOULD have a description to provide additional information 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.
The @since tag is used to denote when an element was introduced or modified, using some description of «versioning» to that element.
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.
The @throws tag is used to indicate whether «Structural Elements» throw a specific type of Throwable (exception or error).
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 that is a subtype of Throwable.
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.
The @todo tag is used to indicate whether any development activities should still be executed on associated «Structural Elements».
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.
Indicates whether the current «Structural Element» consumes the «Structural Element», or project file, that is provided as target.
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.
You may use the @var tag to document the «Type» of the following «Structural Elements»:
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.
element_name 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.
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
Even compound statements may be documented:
The @version tag is used to denote some description of «versioning» to an element.
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.
Version vectors from Version Control Systems are also supported, though they MUST follow the form:
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.
inheritdoc
This element can help minimize the effort required to document complex APIs by allowing common documentation to be inherited from base types/members.
Prior to Visual Studio 2019 version 16.4, this was a custom XML comments element implemented by Sandcastle and the Sandcastle Help File Builder. It does not appear in the list of IntelliSense elements for XML comments prior to that release.
As of November 2019, the select attribute has been deprecated. Use the equivalent path attribute instead which is consistent with the XML comments IntelliSense usage in Visual Studio 2019.
The optional cref attribute overrides the standard search method to allow documentation inheritance from an alternate user-specified member indicated by the member value.
The optional path attribute applies the specified XPath filter expression to the inherited comments. This is useful if you want to limit the inherited documentation to a specific subset of elements or just select a particular instance or set of comments. The expression can be any valid XPath query that will result in a node set.
By making use of the cref and path attributes either by themselves or together, you can fine tune the inheritance of documentation. You can also nest the element within other elements to further refine the level of inheritance.
When using the Sandcastle tools alone, the InheritDocumentationComponent must be added to the BuildAssembler configuration file to handle the inheritdoc elements. When using the Sandcastle Help File Builder, its GenerateInheritedDocumentation tool handles the task of generating the inherited documentation. The following documentation is based on the Sandcastle Help File Builder’s implementation. The build component works in a similar fashion but does not support all of the scenarios related to merging and overriding existing elements.
The inheritdoc element is valid at the root level (i.e. the same level as summary elements) on types, interfaces, virtual members, interface member implementations, and constructors. Its use on any other member type will result in no comments being inherited unless a cref attribute is specified. Note that the element is also valid in project summary and namespace summary comments as long as a cref attribute is specified to indicate from where to inherit the comments. When specified at the root level in a set of XML comments, the documentation search is performed as follows:
If an explicit cref attribute is specified, the documentation from the specified namespace/type/member is inherited. If a cref attribute is not specified, the following rules apply.
For types and interfaces:
Inherit documentation from all base classes working backwards up the inheritance chain.
Inherit documentation from all interface implementations (if any) working through them in the order listed in the reflection information file (usually alphabetically).
Search backwards up the type inheritance chain for a constructor with a matching signature.
If a match is found, its documentation is inherited.
For virtual members and interface implementations:
If the member is an override, documentation is inherited from the member it overrides.
If the member is part of an interface, documentation is inherited from the interface member being implemented.
Explicit interface implementations will automatically inherit documentation from the interface member that they implement if no documentation is supplied by the user. This is done automatically because these members are by definition private and the compiler will not issue a warning if the user does not supply documentation. As such, you can omit the inheritdoc element from them unless you want to customize the comments.
With or without an explicit cref attribute, if the inherited documentation itself contains inheritdoc elements, they will be expanded recursively working backwards up the inheritance chain.
In all cases, if a path attribute is present, it is used to filter the inherited comments based on the specified XPath query.
When inheriting documentation at the root level, if the following elements already exist in the member’s comments, the inherited versions are ignored:
Правильный синтаксис для inheritDoc в phpDocumentor
Каков правильный синтаксис для @inheritDoc в phpDocumentor, если я просто хочу унаследовать всю документацию от родителя? Может быть, более одного синтаксиса является правильным?
Я думаю, что документация довольно расплывчата. PhpStorm, кажется, поддерживает все из них, но, возможно, у меня возникнут проблемы с созданием документов с некоторым синтаксисом?
2 ответа
Я хочу установить phpdocumentor в свой проект Symfony 2.4, поэтому я добавил Эти две строки в свой composer.json: require: < //my old requires phpdocumentor/template-abstract:
1.2, phpdocumentor/phpdocumentor: 2.1.*@dev > когда я выполняю обновление php composer.phar, у меня есть эти ошибки.
Дочерний элемент должен автоматически наследовать почти все из своего родительского docblock без необходимости в этом теге. В противном случае все ваши методы реализации должны были бы быть задокументированы заново, ничего не получив от документации исходного интерфейса.
Просто унаследованный элемент без docblock должен автоматически наследовать все из родительского docblock.
Что касается IDE автозаполнения, я не могу сказать, что я видел последовательное поведение в IDEs, когда дело доходит до этого тега. Кроме того, я видел проекты, в которых предполагается, что этот тег является причиной того, что наследуемая информация от родительских блоков документов даже происходит.
Я ничего не знаю о поддержке IDE, но в документации она называется <@inheritDoc>.
Похожие вопросы:
Какой из следующих способов является правильным для документирования типа возвращаемого значения этого метода для phpDocumentor? Способ 1 : /** * @return array Foo array. */ public function foo() <.
Я испытываю некоторые проблемы с функцией автозаполнения NetBeans. Я использую NetBeans для проекта Symfony2 PHP и phpDocumentor в основном для функции автозаполнения (а не для создания.
Первый день я использую phpDocumentor и до сих пор так хорошо, но у меня есть вопрос, который я не уловил в руководстве. Документация глобальных переменных. Как бы я задокументировал этот код.
Я хочу установить phpdocumentor в свой проект Symfony 2.4, поэтому я добавил Эти две строки в свой composer.json: require: < //my old requires phpdocumentor/template-abstract:
Я установил новый проект symfony 2.4, а также установил phpDocumentor, используя composer.phar, следуя этим шагам: 1-Добавление: require-dev: < phpdocumentor/phpdocumentor: 2.* >к моему.
В composer.json году у меня есть < require: < phpdocumentor/phpdocumentor: * >> Это то, что есть, потому что я пытаюсь установить phpDocumentor в изолированную папку с помощью команды.
Недавно я встречался с PhpDocumentor. Это выглядит как хороший инструмент документации. Я хочу использовать ‘responsive-twig’ в качестве шаблона, который поставляется с phpDocumentor. Я пытался;.
Я пытаюсь запустить PHPDocumentor на локальной установке XAMPP. К сожалению, мне трудно сделать это с помощью менеджеров пакетов. Сначала несколько основных вопросов о менеджерах пакетов: Как.
Inheritdoc php что это
The use of the custom XML comments tag can help minimize the effort required to document complex APIs by allowing common documentation to be inherited from base types/members.
This optional attribute overrides the standard search method to allow documentation inheritance from an alternate user-specified member indicated by the link-ref value.
This optional attribute applies a specified XPath filter expression to the inherited comments. This is useful if you want to limit the inherited documentation to a specific subset of tags or just select a particular instance or set of comments. The expression can be any valid XPath query that will result in a node set.
By making use of the cref and select attributes either by themselves or together, you can fine tune the inheritance of documentation. You can also nest the tag within other tags to further refine the level of inheritance.
The tag is valid at the root level (i.e. the same level as tags) on types, interfaces, virtual members, interface member implementations, and constructors. Its use on any other member type will result in no comments being inherited unless a cref attribute is specified. Note that the tag is also valid in project summary and namespace summary comments as long as a cref attribute is specified to indicate from where to inherit the comments. When specified at the root level in a set of XML comments, the documentation search is performed as follows:
If an explicit cref attribute is specified, the documentation from the specified namespace/type/member is inherited. If a cref attribute is not specified, the following rules apply.
For types and interfaces:
Inherit documentation from all base classes working backwards up the inheritance chain.
Inherit documentation from all interface implementations (if any) working through them in the order listed in the reflection information file (usually alphabetically).
Search backwards up the type inheritance chain for a constructor with a matching signature.
If a match is found, its documentation is inherited.
For virtual members and interface implementations:
If the member is an override, documentation is inherited from the member it overrides.
If the member is part of an interface, documentation is inherited from the interface member being implemented.
Explicit interface implementations will automatically inherit documentation from the interface member that they implement if no documentation is supplied by the user. This is done automatically because these members are by definition private and the compiler will not issue a warning if the user does not supply documentation. As such, you can omit the tag from them unless you want to customize the comments.
With or without an explicit cref attribute, if the inherited documentation itself contains tags, they will be expanded recursively working backwards up the inheritance chain.
In all cases, if a select attribute is present, it is used to filter the inherited comments based on the specified XPath query.
When inheriting documentation at the root level, if the following tags already exist in the member’s comments, the inherited versions are ignored:
