Which of the following elements can be documented by a phpdocumentor?
Packages: Tutorials/Manuals: Show
Files: subpackage DescHTML subpackage DocBlockTags subpackage Errors subpackage InlineTags subpackage Links subpackage ParserData subpackage ParserDocBlock subpackage ParserElements subpackage Parsers subpackage setup subpackage Tutorial subpackage WordParsers
Elements of PHP source that phpDocumentor can automatically documentAuthors: by Gregory Beaver by Chuck Burgess Table of Contents
Procedural Elements include/require/include_once/require_once statements define statements function declarations global variables Class Elements DocBlock inheritance class variables class methods Introduction to Documentable ElementsphpDocumentor is capable of automatically documenting include statements, define statements, functions, procedural pages, classes, class variables, and class methods.Procedural ElementsFrom phpDocumentor's perspective, the basic container for procedural elements (as in real life) is the file that contains them. To reflect this, it is possible to document information about the entire contents of a file. This is accomplished through the use of a page-level DocBlock (see DocBlocks for basic information on what a DocBlock is). A page-level DocBlock is the only DocBlock that cannot precede the element that it is documenting, as there is no way to precede a file. To solve this issue, the way phpDocumentor finds a page-level DocBlock is to parse the first DocBlock in a file as the page-level DocBlock, with certain conditions. This last example has one DocBlock, and it is the first DocBlock in a file, but it is not a Page-level DocBlock. How can phpDocumentor tell the difference between a Page-level DocBlock and any other DocBlock? Simple: In phpDocumentor version 1.2.2, a Page-level DocBlock is the first DocBlock in a file if it contains a @package tag. However, this example will raise a warning like WARNING in test.php on line 8: Page-level DocBlock precedes "define almost", use another DocBlock to document the source element. You can eliminate the warning by adding documentation to the define as follows: Now, the page has its documentation, and the define has its own documentation.So, a DocBlock is a page-level DocBlock IF AND ONLY IF it is both: The first DocBlock in a fileOne of: Contains a @package tagImmediately followed by another DocBlock for any documentable PHP element this is deprecated, always use a @package tagA Page-level DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tags: @package@subpackage CautionphpDocumentor will not document a file like the first example, there must be at least one documentable PHP element in the file.include/require/include_once/require_once statementsphpDocumentor extracts the filename and attempts to link to documentation for that filename if possible. Include statements may only have any of the Standard phpDocumentor Tags phpDocumentor will attempt to locate the included file in the list of files parsed, and if found will make a link to that file's documentation. define statementsA define statement's DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tag:
function declarationsA function's DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tags:
global variablesA global variable's DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tag:
Class ElementsA class's DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tags: @abstract@package@subpackage (adsbygoogle = window.adsbygoogle || []).push({}); @staticDocBlock inheritanceNew in version 1.2.0, DocBlock's are inherited by child classes, variables, and methods. There are a few simple rules for inheritance:
class variablesA class variable's DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tag:
class methodsA method's DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tags:
Documentation generated on Mon, 11 Mar 2019 15:50:05 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004. How to use 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.
When to use PHPDoc?PhpDoc packages are used to group related code elements in the generated documentation. You can specify packages for files and classes and the documented code they contain will inherit the package from them.
What is a documentation block?In programming, a docblock or DocBlock is a specially formatted comment specified in source code that is used to document a specific segment of code. This makes the DocBlock format independent of the target language (as long as it supports comments); however, it may also lead to multiple or inconsistent standards.
What is PHPDoc and why would you use it?PHPDoc is an adaptation of Javadoc for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized.
|