What is Phpdoc?
Not to confuse here I will use the term Dockblock some will call doclet or Phpdoc, it does not matter, what is important is to differentiate the Phpdoc comment from the Phpdoc tool.
The Phpdoc tool automatically generates documentation based on Dockblock code and comments. However you can use other tools to generate this documentation, I particularly prefer Apigen.
Dockblock starts with /*? , they originate from javadoc and may (or may not) have an infinity of tags that start with @;
What use is it?
Docblocks are a means of communication between who makes the code and who consumes it. When you pass your code to third parties, or get a code this documentation will help in understanding, using and modifying it.
They serve as a basis for generating objective documentation that can address a number of issues common to code users.
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 understand the code, on the Phpdoc website there is a list of tags 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 already leaves the issue 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 will make the code publicly available then - like the most common open sources systems in PHP - the more explained the better, otherwise this case is rarely worth the energy to document much.
Remember that you will have to keep the comments consistent with the code, it is very common for the code to be refactored and the comments pass wrong information because they are outdated, so many consider comments as a kind of code duplication.
Any code, function, variable, class, should be clear enough to understand what they do and are within their context, without needing any comment explaining.
When we do not reach this ideal a comment is welcome. It can be a warning, clarification or explanation. But these comments are always failures of our ability to express ourselves through code.
When necessary it should be precise and clear not to confuse, a bad comment more hinders than helps.
There are many tags in the standard phpdoc, but I do not consider it ideal to keep most of this information in a Docblock, when they are in it they are usually just threads. Authoring, version, modification, for example, are better in a version control system. Other examples of bad comments are those obvious or redundant in relation to the code, are just pollution.
Example of 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 normally are the types returned by the functions, types of variables, and types of parameters. Even so only document when induction is not possible (With PHP 7 the need for documentation should decrease). This makes life much easier.
Is there a rule, PSR recommendation on this? If so, which?
The code presentation rules in PSR-2 apply to Docblocks, otherwise there is only one draft under development that may be a recommendation in the future. Can be read here: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md
What’s the difference between PHP comment types?
– rray