Personally, I think any time you have an expected (and strict) format for an array, it would be better to use a Value Object to represent the contents.
This seems like formalizing something that is less than ideal practice. Just my $0.02. -- Woody Gilk http://about.me/shadowhand On Sun, Dec 24, 2017 at 6:02 AM, Andreas Hennings (donquixote) <[email protected]> wrote: > Hello list, > > I want to propose a notation to describe the structure of arrays in a doc > comment, which has worked very well for me in the past. > It would be for @param, @return and @var/@type docs. > I don't know if this should be part of a PSR. Maybe make it some kind of > informal recommendation instead? > > /** > * @param string[][] $labelsGrouped > * Format: $[$typeId][$definitionId] = $label > */ > function printLabels(array $labelsGrouped) {..} > > /** > * @param int[][] $dimensionsAll > * Format: $[] = ['width' => $width, 'height' => $height] > * > * @return int[] > * Format: ['width' => $wMax, 'height' => $hMax] > */ > function dimensionsGetMax(array $dimensionsAll) {..} > > What is new about this? > - The type specifier itself, e.g. "string[][]", is not new at all. > - The description "Format: .." is the new thing I propose. > > Why? > The type specifier does not tell us about the role of array keys. > So far people need long description text to express this information. > The proposed notation, with descriptive (made-up) variable names, is concise > and contains the information that people need. > It is not completely formalized, and not part of the phpdoc type notation > itself, because it is meant for human readers, not the machine. > > How? > The notation mimicks an array value assignment, or an array expresssion. > The root array variable name is shrinked to "$", because a name would not > add any information. > The made-up variable names can resemble other variable or parameter names > used in the application for similar values. Usually this is enough to give > people an idea about their role and type. > Serial (integer) array keys can be omitted, instead just write $[] = $value. > > > I have used this notation extensively, and always found it to be useful. > The only alternatives I have seen are lengthy descriptions, or a lack of > explanation. > > -- Andreas > > -- > You received this message because you are subscribed to the Google Groups > "PHP Framework Interoperability Group" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/php-fig/206a9696-befd-4fb3-b449-f866fd03d39c%40googlegroups.com. > For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6JkWTWaMxoskFdPcsA4bK_3ZmfqR5hnwW88bnyxCG3r3Q%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
