CODEWITHSUNDEEP
phpdocumentationphpdoccode-documentationphpdocumentor2
PajuranCodes
PajuranCodes

Reputation: 481

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+.

Upvotes: 3

Views: 3051

Answers (1)

sebastian_t
sebastian_t

Reputation: 2879

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

Upvotes: 6

Related Questions