Jump to content

PHPDoc: Difference between revisions

From Wikipedia, the free encyclopedia
Browse history interactively
← Previous edit
Content deleted Content added
VisualWikitext
m Reverted 2 edits by 202.83.16.184 identified as test/vandalism using STiki
Petrux (talk | contribs)
75 edits
Undid revision 1249629219 by 2607:FEA8:AA99:EB00:6CAC:CA0B:1936:34D (talk) which replaced the relevant examples with junk code
 
(43 intermediate revisions by 34 users not shown)
Line 1: Line 1:
{{short description|Documentation format for PHP based on Javadoc}}
'''PHPDoc''' is an adaptation of [[Javadoc]] for the [[PHP]] [[programming language]]. It is a formal standard for [[Comment (computer programming)|commenting]] PHP code{{Citation needed|date=December 2011}}. It allows external document generators like [[phpDocumentor]] to generate documentation of [[Application programming interface|APIs]] and helps some [[Integrated development environment|IDEs]] such as [[Zend Studio]], [[NetBeans]], [[PhpStorm|JetBrains PhpStorm]], [[ActiveState Komodo|ActiveState Komodo Edit and IDE]], [[PHPEdit]] and [[Aptana|Aptana Studio]] to interpret variable types and other ambiguities in the [[Typed and untyped languages|loosely typed language]] and to provide improved code completion, type hinting and debugging.
{{For|documentation generator|phpDocumentor}}
'''PHPDoc''' is an adaptation of [[Javadoc]] format for the [[PHP]] [[programming language]]. It is still an informal standard for [[Comment (computer programming)|commenting]] PHP code, but it is in the process of being formalized.<ref name="psr">PHP-FIG: PSR Working Draft - https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md</ref> It allows external document generators like [[phpDocumentor]], which is the de facto standard implementation,<ref name="psr"/> to generate documentation of [[Application programming interface|APIs]] and helps some [[Integrated development environment|IDEs]] such as [[Zend Studio]], [[NetBeans]], [[PhpStorm|JetBrains PhpStorm]], [[ActiveState Komodo|ActiveState Komodo Edit and IDE]], [[PHPEdit]] and [[Aptana|Aptana Studio]] to interpret variable types and other ambiguities in the [[Typed and untyped languages|loosely typed language]] and to provide improved [[autocomplete|code completion]], type hinting and debugging.


PHPDoc supports documentation of both [[object-oriented]] and [[procedural programming|procedural]] code.
PHPDoc supports documentation of both [[object-oriented]] and [[procedural programming|procedural]] code.


On August 13, 2013 the PHP Framework Interoperability Group began writing a formal specification (PSR) for PHPDoc.<ref name="psr"/>
PHPDoc is not currently maintained; the last release was December 3, 2000. There are some up-to-date alternatives, though, such as [[phpDocumentor]] and [[Doxygen]].


== Example ==
On August 13, 2013 the PHP Framework Interoperability Group began writing a formal specification (PSR) for PHPDoc.<ref>PHP-FIG: PSR Working Draft - https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md</ref>
<syntaxhighlight lang="php">

== Components of PHPDoc ==

===DocBlock===

A DocBlock is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. DocBlocks precede the element they are documenting. Any line within a DocBlock that doesn't begin with a * will be ignored.

To document function "foo()", place the DocBlock immediately before the function declaration:

<source lang="php">
/**
/**
* Get all image nodes.
* This is a DocBlock comment
*/
function foo()
{
}
</source>

This example will apply the DocBlock to "define('aklo',2);" instead of to "function foo()":

<source lang="php">
/**
* DocBlock for function foo?
*
*
* @param \DOMNode $node The \DOMDocument instance
* No, this will be for the constant aklo!
* @param boolean $strict If the document has to be valid
*/
define('aklo',2);
function foo($param = aklo)
{
}
</source>

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented, see Elements of the source code that can be documented

A DocBlock contains three basic segments in this order:

* Short Description
* Long Description
* Tags

The Short Description starts on the first line, and can be terminated with a blank line or a period. A period inside a word (like example.com or 0.1%) is ignored. If the Short Description would become more than three lines long, only the first line is taken. The Long Description continues for as many lines as desired and may contain HTML markup for display formatting. Here is a sample DocBlock with a Short and a Long Description:

<source lang="php">
/**
* return the date of Easter
*
* Using the formula from "Formulas that are way too complicated for anyone to
* ever understand except for me" by Irwin Nerdy, this function calculates the
* date of Easter given a date in the Ancient Mayan Calendar, if you can also
* guess the birthday of the author.
*/
</source>

Optionally, you may enclose all paragraphs in a &lt;p&gt;&lt;/p&gt; tag. Be careful, if the first paragraph does not begin with &lt;p&gt;, phpDocumentor will assume that the DocBlock is using the simple double linebreak to define paragraph breaks as in:

<source lang="php">
/**
* Short desc
*
*
* @return \DOMNode
* Long description first sentence starts here
* and continues on this line for a while
* finally concluding here at the end of
* this paragraph
*
* The blank line above denotes a paragraph break
*/
*/
public function getImageNodes(\DOMNode $node, $strict = true): \DOMNode
</source>
{

// ...
Here is an example of using &lt;p&gt;
}

</syntaxhighlight>
<source lang="php">
/**
* Short desc
*
* <p>Long description first sentence starts here
* and continues on this line for a while
* finally concluding here at the end of
* this paragraph</p>
* This text is completely ignored! it is not enclosed in p tags
* <p>This is a new paragraph</p>
*/
</source>

phpDocumentor also supports JavaDoc's DocBlock format through the command-line option -j, --javadocdesc. Due to the non-XHTML compliant unmatched p tag, it is highly recommended to avoid this syntax whenever possible

<source lang="php">
/**
* <p>
* Short desc is only to the first period.
* This means a sentence like:
* "Parses Mr./Mrs. out of $_GET." will
* parse a short description of "Parses Mr."
* which is rather silly. Long description is
* the entire DocBlock description including the
* Short desc, and paragraphs begin where p is like:
* <p>
* The p above denotes a paragraph break
*/
</source>

phpDocumentor will convert all whitespace into a single space in the long description, use paragraph breaks to define newlines, or &lt;pre&gt;, as discussed in the next section.

==== DocBlock Description Details ====

In some parsers the long and short description of a DocBlock is parsed for a few select HTML tags that determine additional formatting. Because not all HTML is allowed, they will generally be converted into plain text or more content specific tags. For example, a &lt;b&gt; tag may be converted into &lt;emphasis&gt; in DocBlock.

Here is a list of tags supported by phpDocumentor:

* &lt;b&gt; -- emphasize/bold text
* &lt;code&gt; -- Use this to surround php code, some converters will highlight it
* &lt;br&gt; -- hard line break, may be ignored by some converters
* &lt;i&gt; -- italicize/mark as important
* &lt;kbd&gt; -- denote keyboard input/screen display
* &lt;li&gt; -- list item
* &lt;ol&gt; -- ordered list
* &lt;p&gt; -- If used to enclose all paragraphs, otherwise it will be considered text
* &lt;pre&gt; -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
* &lt;samp&gt; -- denote sample or examples (non-php)
* &lt;ul&gt; -- unordered list
* &lt;var&gt; -- denote a variable name

For the rare case when the text "&lt;b&gt;" is needed in a DocBlock, use a double delimiter as in &lt;&lt;b&gt;&gt;. phpDocumentor will automatically translate that to the physical text "&lt;b&gt;".

==== Using &lt;code&gt; and &lt;pre&gt; ====

Both &lt;code&gt; and &lt;pre&gt; ignore any HTML listed above (except for their closing tags).

==== DocBlock Templates ====

The purpose of a DocBlock template is to reduce redundant typing. For instance, if a large number of class variables are private, one would use a DocBlock template to mark them as private. DocBlock templates simply augment any normal DocBlocks found in the template block.

A DocBlock template is distinguished from a normal DocBlock by its header. Here is the most basic DocBlock template:

<source lang="php">
/**#@+
*
*/
</source>

The text that marks this as a DocBlock template is "/**#@+" - all 6 characters must be present. DocBlock templates are applied to all documentable elements until the ending template marker:

<source lang="php">
/**#@-*/
</source>

Note that all 8 characters must appear as "/**#@-*/" in order for phpDocumentor to recognize them as a template.

==== Page-level DocBlocks ====

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.

<source lang="php">
<?php
/**
* Page-level DocBlock
*/
define('oops', 'Page-level DocBlock it is not!');
?>
</source>

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:

<source lang="php">
<?php
/**
* Pretend this is a file
*
* Page-level DocBlock is here because it is the first DocBlock
* in the file, and contains a @package tag
* @package pagepackage
*/
define('almost', 'Now the Page-level DocBlock is for the page, and the Define has no docblock');
?>
</source>

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:

<source lang="php">
<?php
/**
* Page-level DocBlock
* @package pagepackage
*/
/**
* Define DocBlock
*/
define('ahhhh', 'Now the Page-level DocBlock is for the page, and the Define DocBlock for the define');
?>
</source>

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 file
# Either:
## Contains a @package tag, or
## Is immediately followed by another DocBlock for any documentable PHP element (this is deprecated, always use a @package tag)

A Page-level DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tags:

* @package
* @subpackage

phpDocumentor will not document a file like the first example, there must be at least one documentable PHP element in the file.

=== Tags ===

Tags are single words prefixed by a "@" symbol. Tags inform parsers how to present information and modify display of documentation as well as allow the IDE to define variable types. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.

{| class="wikitable"
|+ Common tags
! Tag
! Usage
! Description
|-
|@abstract
|
|Documents an abstract class, class variable or method.
|-
|@access
|public, private or protected
|Documents access control for an element. @access private indicates that documentation of element be prevented.
|-
|@author
|author name <author@email>
|Documents the author of the current element.
|-
|@copyright
|name date
|Documents copyright information.
|-
|@deprecated
|version
|Documents a method as deprecated.
|-
|@deprec
|
|Same as @deprecated
|-
|@example
|/path/to/example
|Documents the location of an external saved example file.
|-
|@exception
|
|Documents an exception thrown by a method &mdash; also see @throws.
|-
|@global
|type $globalvarname
|Documents a global variable or its use in a function or method.
|-
|@ignore
|
|Prevents the documentation of an element
|-
|@internal
|
|Private information for advanced developers
|-
|@link
|URL
|Displays a hyperlink to a URL in the documentation
|-
|@name
|global variable name
|Specifies an alias for a variable. For example, $GLOBALS['myvariable'] becomes $myvariable
|-
|@magic
|
|phpdoc.de compatibility {{cite web |url=http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html |title=phpDocumentor tags}}
|-
|@package
|name of a package
|Documents a group of related classes and functions.
|-
|@param
|type [$varname] description
|Documents a function parameter
|-
|@return
|type description
|This tag should not be used for constructors or methods defined with a ''void'' return type.{{citation needed|date=May 2012}}
|-
|@see
|element
|Documents an association to any element (global variable, include, page, class, function, define, method, variable).
|-
|@since
|version
|Documents when a method was added to a class.
|-
|@static
|
|Documents a static class or method
|-
|@staticvar
|type
|Documents a static variable's use in a function or class
|-
|@subpackage
|
|Specifies sub-package to group classes or functions and defines into. Requires @package tag
|-
|@throws
|
|Documents an exception thrown by a method.
|-
|@todo
|
|Documents things that need to be done to the code at a later date.
|-
|@var
|type
|A data type for a class variable
|-
|@version
|
|Provides the version number of a class or method.
|}

In addition, some parsers allow two additional inline tags: {@id}, used to allow direct linking to sections in a tutorial, and {@toc}, used to generate a table of contents from {@id}s in the file. Think of {@id} like an &lt;a name="idname"&gt; HTML tag as it serves the same function.

For more in depth discussion of PHPDoc tags, see http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html

=== Packages ===

To understand the role of packages and how to use @package, it is important to know the logic behind packaging in PHP. The quest for structured programming led to the invention of functions, then classes, and finally packages. Traditionally, a re-usable software module was a collection of variables, constants and functions that could be used by another software package. PHP is an example of this model, as there are many extensions that consist of constants and functions like the tokenizer extension. One can think of the tokenizer extension as a package: it is a complete set of data, variables and functions that can be used in other programs. A more structured format of this model is of course objects, or classes. A class contains variables and functions. A single class packages together related functions and variables to be re-used.

phpDocumentor defines package in two ways:

* Functions, Constants and Global Variables are grouped into files (by the filesystem), which are in turn grouped into packages using the @package tag in a page-level DocBlock
* Methods and Class Variables are grouped into classes (by PHP), which are in turn grouped into packages in a Class DocBlock

These two definitions of package are exclusive. In other words, it is possible to have classes of a different package of the file that contains it.


==See also==
==See also==
Line 351: Line 32:


==External links==
==External links==
* [http://www.docblox-project.org/ DocBlox]
* [http://www.phpdoc.org phpDocumentor.org]
* [http://www.phpdoc.de/ PHPDoc]


[[Category:Documentation generators]]
[[Category:Source code documentation formats]]
[[Category:PHP programming language]]
[[Category:PHP]]

Latest revision as of 06:49, 11 October 2024

For documentation generator, see phpDocumentor.

PHPDoc is an adaptation of Javadoc format for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized.[1] It allows external document generators like phpDocumentor, which is the de facto standard implementation,[1] to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.

PHPDoc supports documentation of both object-oriented and procedural code.

On August 13, 2013 the PHP Framework Interoperability Group began writing a formal specification (PSR) for PHPDoc.[1]

Example

[edit]
/**
 * Get all image nodes.
 *
 * @param \DOMNode     $node       The \DOMDocument instance
 * @param boolean      $strict     If the document has to be valid
 *
 * @return \DOMNode
 */
 public function getImageNodes(\DOMNode $node, $strict = true): \DOMNode
 {
     // ...
 }

See also

[edit]

References

[edit]
  1. ^ a b c PHP-FIG: PSR Working Draft - https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md
[edit]
Retrieved from "https://en.wikipedia.org/enwiki/w/index.php?title=PHPDoc&oldid=1250576161"