search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
360 stars 85 forks source link

Aligning @method syntax with PHP syntax #93

Closed mindplay-dk closed 6 years ago

mindplay-dk commented 9 years ago

PHP 7 now has return type hints and we should think about aligning the @method tag syntax with PHP syntax.

I realize this is a BC break - if we do decide to align this with PHP syntax, we should think about whether it's possible (for implementors) to maintain backwards compatibility with the old syntax. (I think it probably is, since the new syntax use a : to designate the return type.)

I think there is merit to being consistent with native PHP syntax - personally, I would find it confusing to have to switch between two different syntaxes for the same thing, but I'd like to hear what others think?

jacobsantos commented 9 years ago

Yes? I think the problem is that you will still have to support the current style, since it is also supported by IDEs and tools. I agree that being consistent with PHP syntax would be best practices. Also, if the desire is to standardize on using : (colon) character for defining types, then it would be good to use it in more than one place.

mindplay-dk commented 9 years ago

I think the problem is that you will still have to support the current style

To be precise, implementors might (or will) have to support the current style - the spec doesn't have to. I do think it's very important to give careful consideration to the fact that implementors will want to support both (potentially for many years) so I do think they must be compatible, and Appendix B definitely should explain that fact. If we make that change. I'd like to hear what others think.

Fleshgrinder commented 9 years ago

As always, I am pro progress and do not mind BCs. We are developing a new major version, we are allowed to break things. This PSR should definitely cover all of PHP 7's features.

mindplay-dk commented 9 years ago

Alright guys, let me know how that looks to you.

jacobsantos commented 9 years ago

:+1: 1000 times yes. I wasn't much impressed before with using the colon character, but that is much better than the old style.

mindplay-dk commented 9 years ago

@jacobsantos maybe this helps align the : in @template for you as well? :-)

ashnazg commented 6 years ago

PR already open for this, but in the FIG repo itself -- https://github.com/php-fig/fig-standards/pull/899

ashnazg commented 6 years ago

Closing in lieu of https://github.com/php-fig/fig-standards/pull/899 ... please add discussion over there.