php docs IDE

[Ragazzo]

There are a lot of inline php - docs in code, however as i see they have phpstorm format, netbeans use different one - type should go last one as you can see. Can we maybe adjust code or make some workaround ?

[klimov-paul]

Relates #1590

[Ragazzo]

so as i see Netbeans and Eclipse are out of the road , need some workaround here , since Yii is more about useful developing as once was said .

[samdark]

@Ragazzo as I remember, Netbeans supports current format well. Will check it.

[Ragazzo]

No , it does not support it , see above link to Netbeans docs .

[klevron]

+1, I have the same problem with netbeans

[klimov-paul]

Perhaps related: yiisoft/yii#2758

[klimov-paul]

yiisoft/yii#958

[Ragazzo]

should be fixed in the same way as it was done before

[cebe]

Looking at the PHPdoc standard draft they always have the type before the variable name.

https://github.com/php-fig/fig-standards/pull/169/files?short_path=9a10a11#824-var-deprecated
https://github.com/php-fig/fig-standards/pull/169/files?short_path=9a10a11#822-type

I think we should not change our code to outdated usage and rather report this to netbeans that they add support for it.

[klevron]

Yes, but @var tag is used to "document a class property", not for variable type :
https://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/var.html

[klimov-paul]

The main agrument for the current implementation is spoken at #1590:

the current one follows better the standard of phpDocumentor and other doc generator tools.

I personally prefer current syntax: it seems to be more logical:

• when I write function definition I always place type before var name:

public function(MyClass $obj) {}

• when write PHPDoc for virtual property I write type before property name:

/**
 * @property string $name
 */

• if I write a doc comment for isolated var (this issue is about it) I can place its verbose description afterwards:

/**
 * @var Controller $this current controoler
 */

It is a bit odd I have to switch var name and type for this single case.

[Ragazzo]

@klimov-paul not sure about php-documentator, it ignores inline-docs, and here we have problem only with inline docs. I dont think that we should skip this, only because core developers have phpstorm - i think it was main reason for using this inline format.

[cebe]

@Ragazzo the generation of api documentation does ignore inline docs but the PHPDoc standard draft covers this case.
The main reason to use this format is not PHPStorm as PHPStorm supports both afaik. The reason is that it is more natural as described by @klimov-paul.

[Ragazzo]

@cebe if you will remember forms and models issue discussion all arguments there was only about IDE autocomplete , so as i see here you want to skip it ? Why ? If Yii always saying that it is for usability. I dont see here any big problem, once again it is only for inline php-docs.

[klimov-paul]

This issue is sounds more like NetBeans bug (outdated standards or whatever proper name for this is).
Maybe there is some plugin or settings for it?
Still I am not sure: I understand your needs, but you should also understand ours. For me consistency is more valuable then entire set of IDE support (note: we are speaking about not critical issue after all).
But I don't want to decide.

[klevron]

+1 for logical syntax @klimov-paul

But really annoying with Netbeans, problem here is that PHPDOC does not officialy handle this

[klevron]

Don't know about Eclipse, but it seems to accept the same syntax as Netbeans : /* @var $user User */

[qiangxue]

I also think we should keep the current syntax as is. It's dangerous chasing around things. If Netbeans adds support for the new syntax later, it would become Yii's trouble.

[klimov-paul]

Once NetBeans team appraoched us with suggestion of Yii 1.x support:
yiisoft/yii#1536
Perhaps we can contact them, asking about this particular problem.

[Ragazzo]

@qiangxue so as i see, in this issue you ignore usability and IDE autocomplete issues. Not sure if you would be saying that if your IDE was netbeans.

[klimov-paul]

you ignore usability and IDE autocomplete issues

None keeps you from using another code style as well as comments style in your particular project.
But fact that some IDE do not properly handle valid(!) PHPDoc, should not enforce us to maintain core code in other way.

[Ragazzo]

@klimov-paul i have not found any standard for php-doc for inline docs, can you show where on php-doc site it is located? There only php-docs for methods, classes, functions and other.

[cebe]

@Ragazzo I have linked it above.: #3793 (comment)

Also this issue is not about usability or autocompletion as you are talking about inline docs in the framework code. This does not affect users of the framework. It may only affect you slightly when working on the framework itself and then only may not offer good autocompletion.

We use valid PHPdoc comments and your IDE can support this easily, please report it to netbeans. There is no point for us to change framework internal comments to something less straight forward because of lack of support in an IDE that is following old habits.

[Ragazzo]

@cebe your links for php-fig, they have nothing to do with php-docs and how they are implemented.

There is no point for us to change framework internal comments to something less straight forward because of lack of support in an IDE that is following old habits.

i see, so once again, when autocomplete needed by core - developers it is usability and very important, when it needed by other developers (big part of them) it is not Yii problem. Ok )

[klimov-paul]

@Ragazzo, I understand you are upset, but this is not so simple issue as you think.
Still, @samdark, can we contact NetBeans team with this issue or not?

[cebe]

@Ragazzo looks like you have not read what I have linked, it is the draft of the PHPDoc Standard so it really has to do with this.

Your second point is also not true. As explained above, this is not about making core devs more important than others, it is about keeping a consistent usage of documentation. Using type before var in one place and type after var in an other is just not consistent.

[Ragazzo]

@klimov-paul i think we should also contact netbeans developers (not those who developerd Yii plugin). Will see if this issue was raised before there on forums, i dont have any doubts it was )

[klevron]

Searched, not raised since there is no official support for this in phpdoc (only in draft with @type tag)

[klevron]

One last opinion : as I said before I agree for consistency (even if it this not described in phpdoc...), but the big problem I see is that 2 majors IDE (netbeans, eclipse) does not support this... Is there so much phpstorm (which is not free...) users here ??

[samdark]

I'll contact Netbeans team but overall I think we should get maximum amount of IDEs supported out of the box.

[samdark]

Netbeans won't suport the syntax we're using. I think it worth changing it to what's accepted by most IDEs. Will handle it.

[Ragazzo]

so as i see it was phpstorm who made their own choice (not valid choice) and this format is used in fw only because core team using phpstorm ? nice ) should be fixed ofcourse. @samdark do you have any ideas on this one ?

[samdark]

I'm chaning it all to common format that's supported by most of IDEs.

[Ragazzo]

so no support for netbeans and eclipse ?

[cebe]

@Ragazzo ?

[klevron]

Great, thanks @samdark

It is just a matter of gii template after all :)

PS: just for information, I have a little problem about phpdoc in core files with netbeans, e.g. :

/**
 * @var array|null old attribute values indexed by attribute names.
 * This is `null` if the record [[isNewRecord|is new]].
 */
private $_oldAttributes;

Corresponding hint :

Two problems :

• Summary "This is null if the record [[isNewRecord|is new]]." should be before @var. https://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/var.html
• Netbeans does not handle description

[Ragazzo]

@cebe nothing )

[cebe]

@klevron according to PHPdoc you linked all description comes after @var. So this is a Netbeans issue.

The @var tag MAY have a multi-line description and does not need explicit delimiting.

[samdark]

Hmm. There's one more thing. Netbeans doesn't understand the following:

/**
 * @var $this yii\web\View
 * @var $test string
 */

and even the following:

/* @var $this yii\web\View
 * @var $test string
 */

It should be:

/* @var $this yii\web\View */
/* @var $test string */

[klevron]

Yes, it has to be inline

[klevron]

according to PHPdoc you linked all description comes after @var. So this is a Netbeans issue.

@cebe you are right, I was confused by "Summary".

Made a bug report : https://netbeans.org/bugzilla/show_bug.cgi?id=245158

[klevron]

👍