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

Add indicator for optional/defaulted hash values #88

Closed mvriel closed 6 years ago

mvriel commented 9 years ago

When describing hashes using the inline phpdoc notation we should be able to indicate which items are optional or defaulted; this should be described as indicated at https://github.com/phpDocumentor/fig-standards/pull/39#issuecomment-66353617

ashnazg commented 6 years ago

Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions.

I'm on the fence on this one, thinking that it might be fairly easy to work out a syntax for this, but worried it could turn into a time consuming debate for a small use case addition.

neuro159 commented 6 years ago

Can anyone please work on some nice examples here? Both for discussion and test corpus for tools...

ashnazg commented 6 years ago

(as indicated at https://github.com/phpDocumentor/fig-standards/pull/39#issuecomment-66353617)

Example:

@var string $myItem? or

@var string $myItem="Default"

Since we've added nullable types (? prefix) after this original discussion, I think the trailing ? syntax is no longer necessary.

Further, since normally a default value for an optional parameter is going to already be specified in the code signature itself, the only use case I see for the second example is if you want the docs to indicate a default value when the code signature itself is unable to do so. A scenario for this would be if the method is bound by following a parent signature that doesn't include a default value, but the implementation of the child method does provide one... and you want that highlighted by the child method docs.

Again, I'm on the fence on this one (just the second idea... already convinced the first idea is no longer needed).

ashnazg commented 6 years ago

If this needs to be pursued further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig