phpDocumentor / phpDocumentor/phpDocumentor

Which tag to use when using constructor property promotion

Open
#3,626 1 comment 1 reaction 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.