1

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

PajuranCodes
  • 303
  • 3
  • 12
  • 43

1 Answers1

4

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

sebastian_t
  • 2,241
  • 6
  • 23
  • 39
  • 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](https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html) the most used documentation framework (like PHPUnit in code testing)? – PajuranCodes Mar 27 '21 at 09:49
  • @dakis Maybe not as much the PHPDocumentator as the PSR-5 and PSR-19 ( both still in a form of a draft ) https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#arrays – sebastian_t Mar 27 '21 at 15:39
  • 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). – Jeroen van der Laan Mar 27 '21 at 23:52
  • @JeroenvanderLaan Yep. I've added a screenshot to my answer depicting exactly that. – sebastian_t Mar 28 '21 at 00:21
  • 1
    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. – PajuranCodes Apr 02 '21 at 21:48