How to document multiple variable declarations in PHPDoc

Question

I'm using short syntax to define member variables of a class so instead of

private $a;
private $b;
private $c;

I use

private
    $a,
    $b,
    $c;

Now I use PHPDoc to tell the IDE of the type of each member like so:

/** @var classA */
private $a;
/** @var classB */
private $b;
/** @var classC */
private $c;

However this doesn't work with the short syntax:

private
    /** @var classA */
    $a,
    /** @var classB */
    $b,
    /** @var classC */
    $c;

What am I doing wrong?

I'd be surprised if PHPDoc supported documenting the short syntax declarations. Can't you just write them out longhand? — gandaliter
– gandaliter, Commented Sep 29, 2014 at 0:58
This is what I am doing at the moment however when there's many member vars it gets messy, I hoped there was some alternative syntax. — John
– John, Commented Sep 29, 2014 at 1:01

Ian Bytchek · Accepted Answer · 2014-09-30 23:54:41Z

7

Not the answer you want to hear, but that you can't do. PHPDoc isn't as smart as you want it to be, though life on earth would be almost impossible without it.

Besides, things normally start to get messy when people stop following PSR conventions, like declaring multiple properties per statement. So, don't reinvent the wheel, if you don't like the generally accepted way – stick with it and you'll get over this soon enough ;)

Srsly…

answered Sep 30, 2014 at 23:54

Ian Bytchek

9,1156 gold badges50 silver badges77 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

John Over a year ago

I don't understand why declaring multiple properties per statement is considered bad practice though. It keeps the code cleaner, easier to read since you group vars etc. In languages like C++ you are forced to do it that way (private vars under a single "private:" label etc.). Anyway, thanks for the answer :)

Ian Bytchek Over a year ago

Haha this subject is more explosive than the dynamite. PSR is the god sent! It adds a great level of structure to a very forgiving language. Many people don't like how others write their code, but many would make compromises to see others writing code in the same way as they do. This makes everyone's life easier at some point.

MAChitgarha Over a year ago

In addition of PSR-2, PSR-12 (Extended Coding Style) also says you must not declare more than one property per statement.

ashnazg · Accepted Answer · 2022-11-16 14:09:08Z

5

Actually, phpDocumentor 2.x does support the compound declaration, though using one docblock rather than many -- https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/var.html#var

Note that if you don't get the doc results you expect, it may be a bug (like the one shown here -- phpDoc @var for compound statement isn't displayed correctly).

edited Nov 16, 2022 at 14:09

answered Oct 15, 2014 at 21:56

ashnazg

6,7282 gold badges34 silver badges40 bronze badges

2 Comments

Robin Bastiaan Over a year ago

Please show the syntax how it is done according to the phpdoc.org link. Unfortunatly the link does not work anymore, so I can't find the correct syntax.

ashnazg Over a year ago

@RobinBastiaan link updated

Rob · Accepted Answer · 2018-05-15 08:24:30Z

4

If you're looking at similar types; for example:

/** @var string */
private $stringVariable;

/** @var string */
private $stringVariable2;

/** @var string */
private $anotherVariable;

/** @var string */
private $andMoreStringTypes;

you can ofcourse use /** @var string */ for every rule - but you can also use DocBlock templates, like so:

/**#@+
 * @var string
 */
private $stringVariable;
private $stringVariable2;
private $anotherVariable;
private $andMoreStringTypes;
/**#@-*/

answered May 15, 2018 at 8:24

Rob

4,9874 gold badges28 silver badges41 bronze badges

2 Comments

Alexander Schranz Over a year ago

I could not found any official documentation about this syntax, if you have one could you link it here that would be great :)

Rob Over a year ago

@AlexanderSchranz There's still a reference here: manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/… - but it looks like this has been deprecated. Yet, it still works in most IDE's.

Collectives™ on Stack Overflow

How to document multiple variable declarations in PHPDoc

3 Answers 3

3 Comments

2 Comments

2 Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

3 Comments

2 Comments

2 Comments

Linked

Related