PSR-19 - Omitting redundant type declaration

[Nils Rückmann]

The type declaration in DocBlocks dates back to a time when type-hinting was not part of the language. 

IMO there is no reason to keep the type as mandatory part of tags like @param. 

We should be be allowed to omit the type part if it does not add any new information.

Affected tags:

@param

@return

Any thoughts about this? Could not find an ongoing (or ended) discussion about this, if i missed it, please point me to it.

Regards,
Nils

[Anton Fedonjuk]

PSR does not limit the PHP version

среда, 2 октября 2019 г., 11:40:06 UTC+3 пользователь Nils Rückmann написал:

[Asmir Mustafic]

Hi, 

That makes sense to me, there https://github.com/doctrine/coding-standard does already that automatically (there are some bugs with built-in php interfaces as Serializable, but in general works pretty well).

However tools as PHPStorm will still complain about that asking to place the docblocks even if type declarations are present.

Any other PHP-FIG members has a point of view on this? 

Asmir

[Nils Rückmann]

This i not quite true. PSRs always have to be evaluated in a version context.
I guess most of them would not make any sense if we are talking about PHP 4.

Nevertheless, my proposal was to omit the redundant declaration. Which means that it will still be suitable for all versions.

Quick example to demonstrate a version agnostic rule:

> When provided it MUST contain a "Type" to indicate what is expected.

becomes

> When provided it MUST contain a "Type" to indicate what is expected, if not already defined by type hints.

Now all versions are happy. Those versions which do not support type hints for this specific element, can not define a type, which makes the type part mandatory again.

BTW .. if we take PHP 7.4 into account, this proposal would also affect @var tag when its used for describing class properties. 

[Woody Gilk]

I don't think this makes sense. @param declarations should be eliminated if they contain a type, or should expand the type declaration to provide more information, e.g. for arrays.

--
Woody Gilk
https://www.shadowhand.com

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/3aeb94ae-6a66-476a-bfcb-83fa6513b3eb%40googlegroups.com.

[Nils Rückmann]

Besides type declaration, the tag is used to provide a human readable description. I don't think that we should eliminate this option.

To unsubscribe from this group and stop receiving emails from it, send an email to php...@googlegroups.com.

[Larry Garfield]

Honestly I see no point in removing them, not when the de facto standard phpDoc still says to include them, AFAIK.

If we ever manage to finish revamping phpDoc (PSR 5 and 19), and it says to omit types in the @return and @param statements, then future PSRs should follow suit. Existing PSRs are unaffected.

That said, a docblock should be required anyway to specify information that goes beyond just the name and type, which cannot be captured any other way.

--
Larry Garfield
la...@garfieldtech.com

> >> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/3aeb94ae-6a66-476a-bfcb-83fa6513b3eb%40googlegroups.com <https://groups.google.com/d/msgid/php-fig/3aeb94ae-6a66-476a-bfcb-83fa6513b3eb%40googlegroups.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to php-fig+u...@googlegroups.com.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/php-fig/c72f7121-b8a2-4101-9889-a3175ccdac27%40googlegroups.com <https://groups.google.com/d/msgid/php-fig/c72f7121-b8a2-4101-9889-a3175ccdac27%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Ben Mewburn]

I see the reasoning but how is a phpdoc parser going to handle 

/** @return ImNotATypeImADescription make sure you parse me correctly */

function func(): int {} 

[Nils Rückmann]

That's an issue, indeed. I've already thought about it and the only solution I can think of is to mark types explicitly (see jsdoc: `{int}`). This would also allow renderers and IDEs to link types even if they are part of the description. But this is another topic.

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/faa42671-f37e-46e0-a1a0-4eda2f764502%40googlegroups.com.