phpDocumentor

More on 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.

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.

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:

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

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,

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 (https://www.slideshare.net/rdohms/annotations-in-php-they-exist) or view his talk (http://protalk.me/annotating-with-annotations).

Search results