phpDocumentor / phpDocumentor/phpDocumentor
Which tag to use when using constructor property promotion
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 4.3k
- Forks
- 648
- Avg merge
- 28m
- Merged PRs (30d)
- 13
Description
Since PHP 8.0 it is possible to use the promotion constructor property.
see https://php.watch/versions/8.0/constructor-property-promotion.
This leads me to consider which tag I should use to document the promoted properties.
@param, because it is a parameter of the constructor method?
But then phpdocumentor will not indicate that it is also a class property
or @var because it is also a class property
Then the parameter part is missing.
or at worst both tags, which would lead to duplicate comments just for the sake of completeness?
You can't be serious.
So if there is no suitable way to document the promotion of constructor properties with just one tag, then I think introducing a separate tag for this would be a benefit for all developers using this new feature. That way the code doesn't have to contain more comments than necessary.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the PHP 8.0 constructor property promotion reference linked in the issue, then inspect how phpDocumentor currently handles @param and @var for promoted properties. Determine whether an existing tag covers both roles or whether a new tag is needed; done would be a decided, documented approach with an agreed scope for implementation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100