Why must you use phpdoc syntax to document code?
Basic SyntaxThis chapter gives an overview of the syntax of "DocBlocks". The precise effect of a tag including examples are provided in different chapters which are accessible via this document. Show What is a DocBlock?A DocBlock is a special type of comment that can provide verbose information about an element in your code. The information provided in this type of comment can be used by developers to gain understanding of the function of a given element; but it is also used by IDEs to provide (among others) auto-completion and by phpDocumentor to generate API documentation. This is an example of a DocBlock as it can be encountered:
Which elements can have a DocBlockStructural Elements can all be preceded by a DocBlock. The following elements are counted as such:
SectionsA DocBlock roughly exists of 3 sections:
SummaryThe summary is used to give an impression of the function of the documented element. This can be used in overviews to allow the user to skim the documentation in search of the required template. Summaries should always end in either a full stop, or 2 consecutive new lines. If it is not closed like this then any description will be considered as part of the summary. Summaries shall be plain text. Unlike other text elements in DocBlocks Markdown is not supported, nor are tags.
DescriptionThe description contains concise information about the function of the documented element. It is allowed, and encouraged, to use Markdown markup to apply styling. The following list has examples of types of information that can be contained in a description:
Descriptions can also contain inline tags. These are special annotations that can be substituted for a specialized type of information (such as {@link}). Inline tags are always surrounded by braces. A complete listing is provided in Inline tag reference. InheritanceDocblocks automatically inherit the Summary and Description of an overridden, extended or implemented element. For example: if Class B extends Class A and it has an empty DocBlock defined, then it will have the same Summary and Description as Class A. No DocBlock means that the 'parent' DocBlock will not be overridden and an error will be thrown during parsing. This form of inheritance applies to any element that can be overridden, such as Classes, Interfaces, Methods and Properties. Constants and Functions can not be overridden in and thus do not have this behavior. Please note that you can also augment a Description with its parent's Description using the {@inheritdoc} inline tag. Each element also inherits a specific set of tags; which ones depend on the type of element. The following applies:
Please note that @subpackage tags are only inherited if the parent class has the same @package. Otherwise it is assumed that the parent class is part of a library which might have a different structure. What is PHPDoc comment?phpDoc blocks are descriptive comments that are part of the application code. They are used to describe the PHP element in the exact location in the code where the element appears. The block consists of a short description, long description, and phpDoc tags.
How do you document PHP code?Properly document PHP code. Classes. Start every class with /** * Class description * * @author Your organization or personal name * @license MIT (or other licence) */. Properties. Document every property with /** * Property brief description * * @var type */. Methods. ... . Which of the following elements can be documented by a PhpDocumentor?phpDocumentor is capable of automatically documenting include statements, define statements, functions, procedural pages, classes, class variables, and class methods.
How do I run PhpDocumentor?All you need to do is add a file called 'phpdoc. dist. xml' to the root of your project, add your options to it and then invoke the phpdoc command without arguments.
|