[policy only] Documentation standard for arrays of a certain type (param/return types)

Um. If something is an array, it's an array. If it's a Node, it's an object and not an array, right?

@jhodgdon, I think they're talking about what is inside the array.

I do like this idea, in some cases it would give far more detail in terms of what type of array is expected/produced.

I think it would be less useful when stdClasses are used but suplimenting the documentation with expected keys would be helpful.

I like @param array[Drupal\node\Node] $nodes the most although suplimenting this with any non-standard keys (such as a string index to the map) would give even more information, when available.

Oh, you mean it's an array of Node objects?

I would like to see evidence that IDEs recognize syntax like @param array[\Drupal\node\Node] before we even think about adopting it. And note that all namespaces should start with \ in documentation too... And is this standard in other documentation (PHPDoc, JavaDoc, etc.?)

As far as I am concerned, this syntax was far from obvious to human readers, so I would be against adopting it unless it is industry-standard and/or recognized by several major IDEs. If it's just for human readers, maybe we can think of some better way to write it that would be more intuitive for human readers?

OK. Maybe update the issue summary and set to needs review so we can get input?

Updated issue summary.

Thanks! So now we have a concrete proposal. Let's see what people think.

+1 here, already using that in
#2092265: Fix type-hinting for FieldInfo methods
and would be awesome for #2083895: Clean-up comment module doc blocks

Why is this a question? If it is an array of objects of a known interface, you typehint it as such. Core already does this, this is a non-issue.

Here are examples from our codebase.

core/lib/Drupal/Core/Config/Entity/DraggableListController.php
30:   * @var \Drupal\Core\Entity\EntityInterface[]

core/lib/Drupal/Core/Menu/LocalActionManager.php
118:   * @return \Drupal\Core\Menu\LocalActionInterface[]

core/lib/Drupal/Core/Routing/RouteProvider.php
149:   * @return \Symfony\Component\Routing\Route[]

core/modules/aggregator/aggregator.pages.inc
36: * @return \Drupal\aggregator\ItemInterface[]

core/modules/aggregator/lib/Drupal/aggregator/CategoryStorageController.php
27:   * @var \stdClass[]

core/modules/aggregator/lib/Drupal/aggregator/Controller/AggregatorController.php
118:   * @param \Drupal\aggregator\ItemInterface[] $items

core/modules/aggregator/lib/Drupal/aggregator/Form/SettingsForm.php
27:   * @var \Drupal\aggregator\Plugin\AggregatorPluginManager[]
34:   * @var \Drupal\Core\Plugin\PluginFormInterface[]

core/modules/aggregator/lib/Drupal/aggregator/ItemStorageController.php
106:   * @return \Drupal\aggregator\ItemInterface[]

core/modules/aggregator/lib/Drupal/aggregator/ItemStorageControllerInterface.php
51:   * @return \Drupal\aggregator\ItemInterface[]
64:   * @return \Drupal\aggregator\ItemInterface[]
77:   * @return \Drupal\aggregator\ItemInterface[]

core/modules/comment/lib/Drupal/comment/Form/ConfirmDeleteMultiple.php
33:   * @var \Drupal\comment\CommentInterface[]

core/modules/filter/filter.module
198: * @return \Drupal\filter\FilterFormatInterface[]
274: * @return \Drupal\filter\FilterFormatInterface[]

core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
26:   * @var \Drupal\filter\Plugin\FilterInterface[]

core/modules/image/lib/Drupal/image/ImageStyleInterface.php
106:   * @return \Drupal\image\ImageEffectBag|\Drupal\image\ImageEffectInterface[]

core/modules/locale/lib/Drupal/locale/Form/TranslateFormBase.php
82:   * @return \Drupal\locale\TranslationString[]

core/modules/search/lib/Drupal/search/SearchPluginManager.php
52:   * @return \Drupal\search\Plugin\SearchInterface[]
66:   * @return \Drupal\search\Plugin\SearchInterface[]

core/modules/user/lib/Drupal/user/Form/UserPermissionsForm.php
69:   * @return \Drupal\user\RoleInterface[]

core/modules/views/lib/Drupal/views/Plugin/views/field/FieldPluginBase.php
1090:   * @param \Drupal\views\ResultRow[] $values

core/modules/views/lib/Drupal/views/ResultRow.php
25:   * @var array \Drupal\Core\Entity\EntityInterface[]

core/tests/Drupal/Tests/Core/Session/UserSessionTest.php
24:   * @var \Drupal\Core\Session\AccountInterface[]
138:   * @param \Drupal\Core\Session\AccountInterface[] $sessions_with_access
140:   * @param \Drupal\Core\Session\AccountInterface[] $sessions_without_access

It seems that this proposal is (a) in use in Core already and (b) industry standard. Should be non-controversial. Let's leave this at RTBC for now and in about a week I'll update node/1354 (docs standards) to include it.

I don't think we need to do a wholesale core patch at this time once the standard is officially adopted.

It's been a week. :)

Okey dokey! I edited node/1354:
https://drupal.org/coding-standards/docs#types
Let me know if you think it's clear enough.