Inside DocBlocks
Overview
If all is well you have read the Getting Started and got a basic idea on what a DocBlock is and what you can do with it. In this guide I will repeat some of the bits and then dive a lot deeper in and discuss the details on what constitutes a DocBlock and what you can do with it.
Anatomy of a DocBlock
Using a DocBlock you are able to effectively document your application’s API (Application Programming Interface) by describing the function of, and relations between, elements in your source code, such as classes and methods.
In reality a DocBlock is in fact the name for a combination of a, so-called, DocComment and a block of the PHPDoc Domain Specific Language (DSL). A DocComment is the container that contains documentation that can be formatted according to the PHPDoc Standard.
Important
A DocBlock is always associated with one, and just one, Structural Element in PHP; so this may either be a file, class, interface, trait, function, constant, method, property or variable.
DocComments
A DocComment starts with a forward slash and two asterisks (/**), which is similar to how you start a multiline comment but with an additional asterisk, and ends with an asterisk and forward slash (*/). DocComments may be a single line in size but may also span multiple lines, in which case each line must start with an asterisk. It is customary, and recommended, to align the asterisks vertically when spanning multiple lines.
So, a single line DocComment looks like this:
/** This is a single line DocComment. */
And a multiline DocComment looks like this:
/** * This is a multi-line DocComment. */
That is easy, right?
PHPDoc
Something a little more extensive is the PHPDoc DSL. Inside DocComments phpDocumentor, and many other tools with it, expect to find a block of text that matches the PHPDoc Standard.
Commonly a piece of PHPDoc consists of the following three parts in order of appearance:
- Summary
- A short piece of text, usually one line, providing the basic function of the associated element.
- Description
- An optional longer piece of text providing more details on the associated element’s function. This is very useful when working with a complex element.
- A series of tags
- These provide additional information in a structured manner. With these tags you can link to other elements, provide type information for properties and arguments, and more.
Important
The order of these elements matter; you cannot put a summary or description after the tags as it will be seen as part of the last tag.
Summary
The summary is a short but effective overview of an element; you can compare it to a slogan or headline. Summaries are plain and simple, they cannot contain formatting or inline tags (see the next chapter for more information on this) and can be used to skim through, for example, a list of methods.
The summary can be separated from the description in two ways:
With an empty whiteline:
/** * This is a summary * * This is a description */
Or by adding a period followed by a new-line:
/** * This is a summary. * This is a description */
There is not much more to summaries, they are simple and straightforward to use.
Description
This is where the fun starts! A description can be a long text with an elaborate explanation what the associated element does. The description is optional, as there are many elements that are so straightforward that they do not need a length explanation.
Even worse: proper methods are often so simple that a description could be considered overkill!
The nice thing about this description is that you can format your text according to Markdown, more specifically `Github-flavoured Markdown`_. Using this format it is easy to make your text bold, add inline code examples or easily generate links to other sites.
Another nifty feature is that you can use a series of Inline Tags to refer to other parts of the documentation ({@see}), inherit the description of a parent ({@inheritDoc}) and more. Once you finish reading this guide you should definitely take a look at the Inline tag reference to see which Inline Tags there are and what they do.
The description can be as long as you would like and ends when a tag is encountered for the first time.
Tags
Tags are a type of specialized information (meta-data) about the associated element. At the time of writing of this guide PHPDoc counts twenty-eight (28) types of tags.
A tag always starts on a new line with an at-sign (@) followed by the name of the tag. Between the start of the line and the tag’s name (including at-sign) there may be one or more spaces or tabs.
The following is an example of a simple tag:
/** * @source */
In addition to their name each tag may have arguments that can provide additional context specific for that tag. The most common example of this is the @param tag, with which the argument of a method or function is documented:
/** * @param string $argument1 This is the description. */
In the example above we can see that the @param tag features an argument that tells you that the argument with name $argument1 is of type string and has a description This is the description. that, in real life, will tell you the function of that argument.
The best way to discover which options a tag supports is by reading the documentation for that specific tag.
Most tags are associated with a specific element type. So some tags only apply to classes, some only to methods, etc. The easiest way to see to which element a tag applies is to check the documentation for each tag, or consult the table in the next chapter.
List of tags
| 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. |
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 Annotation is 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:
/** * @ORM\Entity(repositoryClass="MyProject\UserRepository") */
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,
Important
Some annotation libraries support Annotations both with and without a namespace. When given the opportunity use a namespace to prevent conflicts with existing tags in the PHPDoc Standard.
When you are using the regular tag syntax it is recommended to prefix the tag with a name representing your application or organisation’s name and a hyphen. For example:
phpdoc-event onClick
To read more on annotations I recommend taking a look at the slides for Rafael Dohms’ talk on annotations (http://www.slideshare.net/rdohms/annotations-in-php-they-exist) or view his talk (http://protalk.me/annotating-with-annotations).
Related topics
- Types, for details on which types are supported by phpDocumentor.
- Inheritance, to read how DocBlocks inherit information from elements in superclasses.
- Your First Set of Documentation, for an introduction in writing DocBlocks.
- PHPDoc reference, for a complete, and more elaborate, reference on the syntax and capabilities of DocBlocks.