Page MenuHomePhorge

Improve PHPDoc of id()
ClosedPublic

Authored by tsc on Apr 12 2024, 19:32.
Tags
None
Referenced Files
Unknown Object (File)
Wed, May 22, 13:56
Unknown Object (File)
Wed, May 22, 13:56
Unknown Object (File)
Wed, May 22, 13:51
Unknown Object (File)
Wed, May 22, 13:49
Unknown Object (File)
Mon, May 20, 18:26
Unknown Object (File)
Sat, May 18, 04:43
Unknown Object (File)
Sat, May 4, 18:54
Unknown Object (File)
Sat, May 4, 18:54

Details

Summary

Improve PHPDoc of id()

Test Plan

Check the types that are returned by id

Diff Detail

Repository
rARC Arcanist
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

tsc requested review of this revision.Apr 12 2024, 19:32

I don’t believe this style of doc annotation is used elsewhere. What’s the purpose of this?

I think the purpose is to tell the IDE that the function receives a type and returns that exact type.

Just for my curiosity, what IDE are you using? :)

In D25576#16575, @speck wrote:

I don’t believe this style of doc annotation is used elsewhere. What’s the purpose of this?

It is to indicate language server aware editors what type the object has and this results in code completion to work:

CleanShot 2024-04-13 at 22.19.51.png (544×1 px, 161 KB)

For more details, see here:

https://phpstan.org/blog/generics-in-php-using-phpdocs#type-variables

Unless we can come up with a better/more common notation to show this information, I'm +1 on this - I like static type information, and this one looks fine to me.
I'm not familiar with many PHP tools - is there another notation somewhere?

AFAIK, this https://we.phorge.it/book/arcanist/function/id/ is the only thing we do with the annotation (other then having it for humans). I don't think we have any home-grown static type checks.

Unless we can come up with a better/more common notation to show this information, I'm +1 on this - I like static type information, and this one looks fine to me.
I'm not familiar with many PHP tools - is there another notation somewhere?

Seems like there is not a standard for it, but many of the implementation seem to support it:

AFAIK, this https://we.phorge.it/book/arcanist/function/id/ is the only thing we do with the annotation (other then having it for humans). I don't think we have any home-grown static type checks.

I think I'll tinker in my extensions with these toolings 🤔

Maybe at one point, if it provides any values, we can adopt some of these techniques into core.

Premising I've already seen this syntax in Java but not in PHP, I'm happy that now your IDE says something useful. Maybe a better title is "Improve PHPDoc of id()".

sgtm

This revision is now accepted and ready to land.Apr 15 2024, 13:09
tsc retitled this revision from provide proper typings for `id` function to Improve PHPDoc of id().Apr 15 2024, 14:12
tsc edited the summary of this revision. (Show Details)
This revision was automatically updated to reflect the committed changes.