search

yiisoft / yii2-gii

Yii 2 Gii Extension
http://www.yiiframework.com
BSD 3-Clause "New" or "Revised" License
202 stars 192 forks source link

Comments which includes @var properties aren't DocBlocks #425

Closed ricpelo closed 4 years ago

ricpelo commented 4 years ago

The comments which include @var properties aren't DocBlocks. They must be started with /**, not /*.

The issue affects both the yii2-gii code and the code generated by gii.

Q A
Yii version 2.0.32
Yii2-gii version 2.1.4
PHP version 7.3
Database version
Operating system Linux
samdark commented 4 years ago

They're called vardoc and originated from Eclipse PDT. Then they were adopted by all other IDEs. They're well supported. What is the issue with these?

ricpelo commented 4 years ago

They're called vardoc and originated from Eclipse PDT. Then they were adopted by all other IDEs. They're well supported. What is the issue with these?

I didn't knew that. I only tried Visual Studio Code with PHP Intelephense extension as well as Atom with PHP Serenata package and they don't like @var outside DocBlocks.

samdark commented 4 years ago

I see. If there are editors that can't work with such format, let's fix it.

ricpelo commented 4 years ago

Oops, I just tested it and I think I made a mistake. Visual Studio Code with PHP Intelephense extension does honor /* @var */ syntax and doesn't honor /** @var */ syntax. On the other hand, Atom doesn't honor neither. Could you please roll back the PR until we can make sure it worth merging it? After some tests, it seems to brings more harm than benefit. Thanks and sorry!

samdark commented 4 years ago

:)

samdark commented 4 years ago

Reverted.

ricpelo commented 4 years ago

Thanks again! I'll investigate further.

rob006 commented 4 years ago

Vardoc and phpdoc have different order:

/* @var $variableName type */
/** @var type $variableName */

So simple removing or adding * is not enough.

It is also questionable if using dockblocs is correct in some cases (like in views, where there is no structural element to document), and some tools complains about it (PHP-CS-Fixer have have fixers for this).

ricpelo commented 4 years ago

Vardoc and phpdoc have different order:

/* @var $variableName type */
/** @var type $variableName */

So simple removing or adding * is not enough.

It is also questionable if using dockblocs is correct in some cases (like in views, where there is no structural element to document), and some tools complains about it (PHP-CS-Fixer have have fixers for this).

You're right, @rob006 . Switching variable and type order gets Visual Studio Code works.

It's a very interesting tool in views too, because the IDE can autocomplete from the $variableName.

Compare this (without phpdoc):

2020-02-13-181035_976x858_scrot

With this (with phpdoc):

2020-02-13-180915_981x854_scrot

samdark commented 4 years ago

That's how it should always work and it works like that in PhpStorm, PDT, NetBeans.

pigochu commented 4 years ago

@samdark

https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md

PSR-5 use /* @var ... / , ex /* @var \Sqlite3 $sqlite /

I changed my IDE from netbeans to vs code , because Netbeans is slow and not support WSL. but vs code only support /* @var \Sqlite3 $sqlite /

Does yii2/yii3 follow the PSR-5 specification ?

samdark commented 4 years ago

No, it doesn't since PSR-5 isn't accepted yet and IDEs aren't ready.