Official PHPDoc reference for documenting PHP code

Question

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

sebastian_t · Accepted Answer · 2021-04-03 19:53:31Z

6

+100

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.

edited Apr 3, 2021 at 19:53

answered Mar 27, 2021 at 8:30

sebastian_t

3,0696 gold badges27 silver badges42 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

PajuranCodes Over a year ago

Hi, Sebastian. Thank you for your answer. I'll revise all answers after the 7 days. Would you mind completing a bit with what you meant by "for code completion standpoint"? Also, from your knowledge, is phpDocumentor the most used documentation framework (like PHPUnit in code testing)?

sebastian_t Over a year ago

@dakis Maybe not as much the PHPDocumentator as the PSR-5 and PSR-19 ( both still in a form of a draft ) github.com/php-fig/fig-standards/blob/master/proposed/…

Jeroen van der Laan Over a year ago

To elaborate on the "for code completion standpoint": PHPDoc helps the IDE to strengthen PHP's dynamic type system. The return type of function foo(): array is mixed[] by default, but can be annotated with @return string[] in order to have the IDE narrow this type down to string[], which in turn allows for better code completion. In my opinion this is the most important use case of PHPDoc, and should be applied as such whenever possible (despite PHP versions).

sebastian_t Over a year ago

@JeroenvanderLaan Yep. I've added a screenshot to my answer depicting exactly that.

PajuranCodes Over a year ago

Sebastian, I studied PSR-5 and PSR-19. Awesome! Exactly what I was hoping to find out when I asked the SO question. Until now I implemented some of the PSR interfaces/standards, though these ones I somehow missed :-) Could you please write about the two PSR's in the answer too (e.g. not just in the comment)? Thank you very much again. Have fun.

Collectives™ on Stack Overflow

Official PHPDoc reference for documenting PHP code

1 Answer 1

5 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

5 Comments

Your Answer

Sign up or log in

Post as a guest

Related