For the examples provided, you would need value classes like ListOfListOfSomething, and internally you would still have your nested arrays. Also if you want to gradually want to collect items into a grouped structure, you would need a mutable value object. I don't think you can fully avoid nested arrays like int[][] or Item[][]. Even if you only use them for internal data crunching, it can be useful to document it with a @var doc.
An example are the private fields in Compose ClassLoader. https://github.com/composer/composer/blob/master/src/Composer/Autoload/ClassLoader.php Some of them have the format string[][]. I don't think replacing them with value objects would be smart. The authors decided to not put individual docs on these variables. Achoice I respect :) But if you would want to document the role of each array key, you could use the format I propose here. On Dec 25, 2017 1:37 AM, "Woody Gilk" <[email protected]> wrote: > 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 a topic in the > Google Groups "PHP Framework Interoperability Group" group. > To unsubscribe from this topic, visit https://groups.google.com/d/ > topic/php-fig/8QfU5-I_myM/unsubscribe. > To unsubscribe from this group and all its topics, 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. > -- 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/CAH0Uv3Hat3m3X4mp%2BE6n%2BrdO1V%3D%3Dg2mQ7LSe2NxO6m%2B%3DmWVdSA%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
