phpdocumentationphpdoccode-documentationphpdocumentor2

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:

Option 2:

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. enter image description here