PHP Documentation DocBlock Documentor - PHP Comments

PHP DocumentorPhp Documentor

A DocBlock looks like this:

 
 /**
  * A summary informing the user what the associated element does.
  *
  * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
  * and to provide some background information or textual references.
  *
  * @param string $myArgument With a *description* of this argument, these may also
  *    span multiple lines.
  *
  * @return void
  */
  function myFunction($myArgument)
  {
  }

Please see the tag reference for the canonical list of tags and their complete descriptions.

Annotations

In addition to the above you might also encounter Annotations when viewing DocBlocks. An Annotationis a specialized form of tag that not only documents a specific aspect of the associated element but also influences the way the application behaves.

Annotations come in various forms, many look exactly like normal tags but some have a more complicated syntax:

/**
 * @ORMEntity(repositoryClass="MyProjectUserRepository")
 */

In the example above we demonstrate how you define that a class represents a database entity in Doctrine; as you can see the tag name is separated into two parts, a namespace and the actual annotation name,

 
   
Tag Element Description
api Methods declares that elements are suitable for consumption by third parties.
author Any documents the author of the associated element.
category File, Class groups a series of packages together.
copyright Any documents the copyright information for the associated element.
deprecated Any indicates that the associated element is deprecated and can be removed in a future version.
example Any shows the code of a specified example file or, optionally, just a portion of it.
filesource File includes the source of the current file for use in the output.
global Variable informs phpDocumentor of a global variable or its usage.
ignore Any tells phpDocumentor that the associated element is not to be included in the documentation.
internal Any denotes that the associated elements is internal to this application or library and hides it by default.
license File, Class indicates which license is applicable for the associated element.
link Any indicates a relation between the associated element and a page of a website.
method Class allows a class to know which ‘magic’ methods are callable.
package File, Class categorizes the associated element into a logical grouping or subdivision.
param Method, Function documents a single argument of a function or method.
property Class allows a class to know which ‘magic’ properties are present.
property-read Class allows a class to know which ‘magic’ properties are present that are read-only.
property-write Class allows a class to know which ‘magic’ properties are present that are write-only.
return Method, Function documents the return value of functions or methods.
see Any indicates a reference from the associated element to a website or other elements.
since Any indicates at which version the associated element became available.
source Any, except File shows the source code of the associated element.
subpackage File, Class categorizes the associated element into a logical grouping or subdivision.
throws Method, Function indicates whether the associated element could throw a specific type of exception.
todo Any indicates whether any development activity should still be executed on the associated element.
uses Any indicates a reference to (and from) a single associated element.
var Properties  
version Any indicates the current version of Structural Elements.

 

Visit sunny St. George, Utah, USA