I'm mostly used to seeing class properties documented like, e.g.:
/**
* Summary of property.
*
* @var array
*/
protected $data = [];
In the current PSR-5 and PSR-19 drafts, all the examples for @var show the
single-line syntax like, e.g.:
/** @var array Description of property (from tag). */
protected $data = [];
It's currently not clear where the property's description SHOULD be placed.
I've seen three editor implementations that show different results in the
autocomplete hint for the property:
1. shows the DocBlock summary/description but not the @var tag
description.
*e.g. "Summary of property." (or empty)*
2. shows the @var tag description but not the DocBlock
summary/description.
*e.g. "Description of property (from tag)."** (or empty)*
3. shows both the DocBlock summary/description and the @var tag
description.
*e.g. "Summary of property. Description of property (from tag)."*
So depending on which of the above documentation styles has been used, some
editors show no description for the property. I came looking at the
PHPDocumentor docs and the latest PSR drafts to find out which
implementation was correct, but there doesn't seem to be any
standard/recommendation that answers this question.
It would be good to address these issues in the new PSRs:
- Should PHPDoc implementations show *both *the DocBlock
summary/description *and *the @var tag description, or just *one *of
them, and if so, which one?
- If there can only be one DocBlock with only one @var tag before a
property/variable:
- Does it make sense to have two different ways to do the same thing
(describe the property)? Should the @var tag description be removed from
the spec?
- If the @var tag description shouldn't be removed because it's
required for other usages of the @var tag, should the PSRs specify a
different *meaning/context *of the @var tag description compared to
the DocBlock summary/description, that would make it clear:
- when to use the tag description *instead *of the DocBlock
summary/description, or
- whether to provide *different contextual content *in the tag
description than in the DocBlock summary/description?
--
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 [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/php-fig/90b68cca-00ed-4cb1-ad17-6a4e02e2cc47%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
