[PSR-5][PSR-19] Standard for describing properties with the @var tag

[Andrew Goode]

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?

[Chuck Burgess]

Thanks for the thread, Andrew.

I've added to my TODO notes for the @var Tag that an example of a full DocBlock needs to be the basic example (like your first example), with the one-line DocBlock variant being an allowed alternative syntax.

More generally addressing your question for the One True Way, in this instance, I see *all* the ways as OK.  Here's why:

* The DocBlock level Description is optional and available, regardless of the Tags in the DocBlock... the fact that this this particular DocBlock is only for an element that the @var Tag itself will describe is irrelevant, even if it seems redundant.

* The @var Tag level Description is optional and available, because not all well-named elements with properly shown @var data Type will need such description... the fact that the DocBlock itself has an optional Description is irrelevant, even if it seems redundant.

* The one-line DocBlock format variant doesn't allow for Summary or Description, so the @var Tag level Description is the only place to put one if such a description is needed.

Now, if we were to consider trying to remove the variations and force a One True Way here, I fear we will find three statistically equal camps out in the wild with regard to how projects use this Tag and its DocBlock.

However, if the Working Group did wish to try tightening up this case of description redundancy, then presumably the cleanest way to do so is to drop Description completely out of the @var Tag itself, since we can't really force dropping it from the DocBlock overall just because it's an @var Tag DocBlock.

Working Group and ML readers:  further thoughts?

CRB
about.me/ashnazg

--
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 post to this group, send email to php...@googlegroups.com.
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.