Informal array format description notation

[Andreas Hennings (donquixote)]

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

[Woody Gilk]

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

> --
> 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 php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> 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.

[Andreas Hennings]

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.

> email to php-fig+unsubscribe@googlegroups.com.

> To post to this group, send email to php...@googlegroups.com.
> 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 php-fig+unsubscribe@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6JkWTWaMxoskFdPcsA4bK_3ZmfqR5hnwW88bnyxCG3r3Q%40mail.gmail.com.