Variable arguments (rest params)

[mindplay-dk]

It seems the ... syntax for @param was omitted from the current spec.

The legacy php-doc description prescribes a syntax like:

@param string $names,...

I guess maybe we'd have to preserve the legacy syntax for backwards compatibility?

There are several problems with the legacy syntax, mainly the type-hint is singular which is inconsistent with other languages, and creates a problem when the collection type is anything other than an array (e.g. generic types under the new spec) and the syntax as such is also inconsistent with e.g. ECMA6, Typescript, Dart, and others.

I would propose:

@param ...string[] $names

This is consistent with other languages, and permits the use of other collection types, e.g.:

@param ...ArrayObject $names

Thoughts?

[Fleshgrinder]

What BC? I know that this was mentioned several times here, but this is the first PSR for documentation and it only serves as a recommendation. Only tools have to deprecate, this PSR does not. Imho!

I like your suggestion and I like that it is consistent with other languages.

[mindplay-dk]

This may be the first PSR, but it's based on a de-facto standard. We can't ignore 10 billion lines of existing PHP code. At the very least, the meta-doc needs to clarify any BC breaks or deprecations of previous de-facto standards.

[mindplay-dk]

Okay, typing this up, I'm realizing what I wrote doesn't quite make sense:

the type-hint is singular which is inconsistent with other languages, and creates a problem when the collection type is anything other than an array

It's inconsistent for a reason - because PHP doesn't actually support rest params, the actual type passed is always going to be an array, it can't be anything else, because you have to pick it up inside the function using func_get_args() and slice it yourself, so... my ArrayObject example makes no sense, and the "BC break" of specifying the rest param type as an array also makes no sense.

So if the arguments are a list of strings, you would write:

@param ... string $names

This is closer to what we had in de-facto standard php-doc, only fine-tuned with more commonly-used leading ... instead of trailing ,...

I'm working on a PR.

[mindplay-dk]

@mvriel I started Appendix B in this PR, which had not been started yet. Looks like there's a bunch of work to do there - is there an open issue for that? We could flag as "help wanted" and try to get this moving. I will be making more contributions, but let's see if we can bring more people on-board and doing some of this grunt work :-)

[mvriel]

@mindplay-dk for appendix B there is no issue yet; we should make an inventory of which things specifically changed and then we can add issues for each of those (or write them)

[mvriel]

@mindplay-dk regarding the notation; I would insist that we be consistent with PHP's implementation and when suggesting a variadic prepend the variable name with an elipsis (...). See my feedback on PR #87

[mvriel]

For reference, this is the PHP RFC dealing with variadics: https://wiki.php.net/rfc/variadics

Let's continue this discussion in #87; I will be closing this issue to prevent fragmentation of the discussion

[Fleshgrinder]

This may be the first PSR, but it's based on a de-facto standard. We can't ignore 10 billion lines of existing PHP code. At the very least, the meta-doc needs to clarify any BC breaks or deprecations of previous de-facto standards.

I disagree, because you'd have to go out and check all existing tools there are.

[mindplay-dk]

you'd have to go out and check all existing tools

No, php-documentor defines the de-facto standard - we need to document differences from it, in order to help and guide people towards the new PSR, to help them change old habits and adopt new features. I don't think anyone expects us to compare with every non-standard feature invented or supported by other tools.

[Fleshgrinder]

Of course not, my point is simply that the PR should not be to tightly bound to the current phpDocumentor implementation and better break things in favor of defining a new and good standard.