Documenting associative array keys

Hello,

I couldn't find any other issues about this so I'm hoping I'm not creating a duplicate.

I would really like to see the ability to document the array keys of associative arrays, to allow IDEs to implement autocomplete.

Don't really have a proposal on how this should be implemented tag-wise, I'll leave that to the experts...

[mvriel]

This isn't a duplicate of an existing issue but there have been discussions regarding the notation for this element.
You can find a draft here: https://github.com/phpDocumentor/phpDocumentor2/pull/645/files#L0R1655

Please note that this is a draft and can still be changed depending upon community feedback

[boenrobot]

I like the @struct idea, but I'm not sure about the "inline DocBlock" part.

It took me a full minute to unpack what it meant to say. More importantly though, what do you do if your array keys contain spaces?

That said, I'm not sure what to propose as an alternative, short of a full blown PHP parser being in there, with "inline DocBlock" for every key/value pair.

[mvriel]

I will document the full proposal in the PSR document; perhaps that will clarify the intent

[donquixote]

(I did not find a more relevant or more recent discussion, so I am posting here..)

What about this?

/**
 * @param {
 *   type: string
 *   query: SelectInterface
 *   options: {
 *     color: string = 'blue'
 *   }
 * }[] $items
 */
function foo($items) {
  foreach ($items as $item) {
    $item['query']->execute()->fetchAll();
  }
}

[mvriel]

You can also look at https://github.com/phpDocumentor/fig-standards/issues/30 for more information. We are working on new syntax for that as part of the upcoming PSR

[bannostookaylo]

I saw this has been added to the road map any status on how close its becoming to being implemented?

[mvriel]

At current we are re-evaluating our priorities after a hiatus. This means that at this moment I am unable to answer the question

[jcrben]

For those looking at the latest fig-standard discussion, it appears it migrated to https://github.com/phpDocumentor/fig-standards/issues/7

I mentioned this on Stack Overflow in a couple places, e.g. https://stackoverflow.com/questions/9132062/is-there-a-way-for-phpdoc-to-document-an-array-of-objects-as-a-parameter - I am accustomed to the JavaScript ecosystem where this is more common (see, e.g., React PropTypes shape https://facebook.github.io/react/docs/typechecking-with-proptypes.html#proptypes).

[CC007]

What is the status on this issue at this time?

[jcrben]

@CC007 it sounds like @ashnazg is planning to revive the related FIG at some point https://github.com/phpDocumentor/fig-standards/issues/7#issuecomment-361356407