php documentation phpdoc code-documentation phpdocumentor2

Official PHPDoc reference for documenting PHP code

I'm on my way to upgrade my projects to PHP 8.0+. Until now, in the code comments, I used the @param and @return tags like in "option 1", instead of like in "option 2":

Option 1:

@param string[] ....
@return User[] ....

Option 2:

@param array ....
@return array ....

Though, because I don't know if the first form is officially allowed, I begin to ask myself, if it wouldn't be better to switch to the second option... So, I'd like to ask you: Is there any official PHPDoc reference for documenting PHP codes available?

Also, is it at all advisable to use the first option instead of the second one? In other words: are there any arguments speaking against it - having the future in mind too?

Thank you for your time.

P.S: I found the reference of PHPDocumentor, but I have the feeling, that it is not the official PHP one and not (yet) compatible with PHP 8.0+.

Solution

PHPDoc isn't a part of the official documentation but since it has been so widely adapted I highly doubt it will be ignored.

PHP itself prior to version 8 defines only comment syntax https://www.php.net/manual/en/language.basic-syntax.comments.php which does not include any @ related elements.

Version 8 of PHP introduces attributes https://www.php.net/manual/en/language.attributes.overview.php which will be the native replacement for annotations.

For example https://api-platform.com/docs/core/filters/

PHP till 7.x

/**
 * @ApiResource(attributes={"filters"={"offer.date_filter"}})
 */
class Offer
{
    // ...
}

Since PHP 8

#[ApiResource(attributes: ['filters' => ['offer.date_filter']])]
class Offer
{
    // ...
}

PSR Standard

PHP FIG defined 2 PSR standards ( Not approved yet )

Though, because I don't know if the first form is officially allowed, I begin to ask myself, if it wouldn't be better to switch to the second option...

I will just stick with the Option 1. It is extremely beneficial for code completion standpoint.