PHPDoc - What is it, what is its usefulness and how to use it?

What is PHPDoc?

To not confuse here I will use the term DockBlock some will call doclet or PHPDoc, this does not matter, what is important is to differentiate the PHPDoc comment from the PHPDoc tool.

The PHPDoc tool generates documentation automatically based on code and in DockBlock comments. But you can use other tools to generate this documentation, I particularly prefer ApiGen.

The DockBlock starts with / **, they come from javadoc and may (or may not) have an infinite number of tags that begin with @;

How useful are you?

Docblocks are a means of communication between who makes the code and who consumes it. When you pass your code to third parties, or obtain a code, this documentation will help in understanding, using and modifying it.

They serve as the basis for generating objective documentation that can address a number of issues common to those who consume the code.

Can I freely use the code in my projects? (@license); Who is the author of the code? (@author); What does this function return? (@return); etc.;

These tags communicate well with the machine they help the IDE to understand the code, in the PHPDoc website there is a list of tags that are supported by the documentation generation tools.

There are also frameworks like Doctrine and PHPUnit that accept their own tags in these comments. With them it is possible, for example, to map and generate the entire database or entities of an application with Doctrine, but this use is out of the question of documentation.

How to use?

Within the philosophy of Robert C. Martin the basic rule I recommend is: put as few comments as possible but enough to be clear.

The exception is if you are going to make the code publicly available then - like the most common open source systems in PHP - the more explained the better, otherwise it is rarely worth the energy to document a lot.

Remember that you'll have to keep the comments consistent with the code, it's very common for the code to be refactored and the comments go wrong because they are out of date, so many consider comments as a type of code duplication.

Any code, function, variable, class, must be clear enough to understand what they do and are within their context, without needing any explaining comments.

When we do not reach this ideal a comment is welcome. It can be an alert, clarification or explanation. But these comments are always failures of our ability to express ourselves through code.

When necessary it should be accurate and clear not to confuse, a bad comment is more cumbersome than it helps.

There are a lot of tags in the phpdoc pattern, but I do not consider it ideal to keep most of this information in a DocBlock, when it's usually just a signature in it. Authorship, versioning, modification, for example look better on a version control system. Other examples of bad comments are those obvious or redundant in relation to the code, they are just pollution.

Sample useless documentation:

/**
* Entidade Usuário
*/
class user {
    /**
    * nome do usuário
    */
    $nome;

    //...

    /**
     *Estabelece o Nome do usuário
     */
    function setName(){//... }

    /**
     *Pega o Nome do usuário
     */
    function getName(){//... }

    // … 

}

What is worth documenting are typically the types returned by functions, variable types, and parameter types. Even so document only when induction is not possible (With PHP 7 the need for documentation should decrease). This makes life much easier.

Do you have any rule, PSR recommendation on this? If so, which one?

The code presentation rules in PSR-2 apply to DocBlocks, otherwise there is only one draft in development that might be a recommendation in the future. It can be read here: link

PHPDoc is a way of adding information about a structure (method or class etc) they are useful for some tools that automatically generate documentation from these 'comments'. This information is important for IDE with them your classes go into auto-complete so it's easy to go browsing from one method to another.

To use doclet is almost equal to a comment the important fact is that after the bar two consecutive asterisks are needed.

/** doclet
/* comentário

PHPDoc was based on Sun's JAVADoc and aims to standardize PHP code documentation. It reads the code and parses by looking for special tags. From them extracts all documentation using different formats (pdf, xml, html, chm Windows help and others). All special tags are written within the php comments / * comments * / and necessarily begin with @ (at).

Description of some special tags:

@access Especifica o tipo de acesso (public, protected e private).  
@author Especifica o autor do código/classe/função.  
@copyright Especifica os direitos autorais.  
@deprecated Especifica elementos que não devem ser usados.  
@exemple Definir arquivo de exemplo, $path/to/example.php  
@ignore Ignora código  
@internal Documenta função interna do código  
@link Link do código  
@see Define uma referência a outro elemento ou uma URI  
@since Define a partir de qual versão os elementos estruturais foram disponibilizados  
@name Especifica o apelido (alias).  
@package Especifica o nome do pacote pai, isto ajuda na organização das classes.  
@param Especifica os paramêtros (muito usado em funções).  
@return Especifica o tipo de retorno (muito usado em funções).  
@subpackage Especifica o nome do pacote filho.  
@version Especifica a versão da classe/função.  

To generate the documentation, you can install the tool using PEAR, Composer or manual download.

References: Code Line
PHPDoc