Je préfère lire et écrire du code propre - comme indiqué dans "Clean Code" de Robert C. Martin. Lorsque vous suivez son credo, vous ne devez pas obliger le développeur (en tant qu'utilisateur de votre API) à connaître la structure (interne) de votre tableau.
L'utilisateur de l'API peut demander: est-ce un tableau avec une seule dimension? Les objets sont-ils répartis à tous les niveaux d'un réseau multidimensionnel? De combien de boucles imbriquées (foreach, etc.) ai-je besoin pour accéder à tous les objets? Quels types d'objets sont "stockés" dans ce tableau?
Comme vous l'avez indiqué, vous souhaitez utiliser ce tableau (qui contient des objets) comme un tableau unidimensionnel.
Comme indiqué par Nishi, vous pouvez utiliser:
/**
* @return SomeObj[]
*/
pour ça.
Mais encore une fois: soyez conscient - ce n'est pas une notation standard de docblock. Cette notation a été introduite par certains producteurs IDE.
D'accord, d'accord, en tant que développeur, vous savez que "[]" est lié à un tableau en PHP. Mais que signifie "quelque chose []" dans un contexte PHP normal? "[]" signifie: créer un nouvel élément dans "quelque chose". Le nouvel élément pourrait être tout. Mais ce que vous voulez exprimer, c'est: tableau d'objets avec le même type et c'est le type exact. Comme vous pouvez le voir, le producteur IDE introduit un nouveau contexte. Un nouveau contexte qu'il fallait apprendre. Un nouveau contexte que d'autres développeurs PHP ont dû apprendre (pour comprendre vos docblocks). Mauvais style (!).
Parce que votre tableau a une dimension, vous voudrez peut-être appeler ce "tableau d'objets" une "liste". Sachez que "liste" a une signification très spéciale dans d'autres langages de programmation. Il serait préférable de l'appeler "collection" par exemple.
N'oubliez pas: vous utilisez un langage de programmation qui vous permet toutes les options de POO. Utilisez une classe au lieu d'un tableau et rendez votre classe traversable comme un tableau. Par exemple:
class orderCollection implements ArrayIterator
Ou si vous souhaitez stocker les objets internes à différents niveaux dans une structure de tableau / objet multidimensionnelle:
class orderCollection implements RecursiveArrayIterator
Cette solution remplace votre tableau par un objet de type "orderCollection", mais n'activez pas la complétion de code dans votre IDE jusqu'à présent. D'accord. L'étape suivante:
Implémentez les méthodes introduites par l'interface avec docblocks - en particulier:
/**
* [...]
* @return Order
*/
orderCollection::current()
/**
* [...]
* @return integer E.g. database identifier of the order
*/
orderCollection::key()
/**
* [...]
* @return Order
*/
orderCollection::offsetGet()
N'oubliez pas d'utiliser l'indication de type pour:
orderCollection::append(Order $order)
orderCollection::offsetSet(Order $order)
Cette solution arrête d'introduire beaucoup de:
/** @var $key ... */
/** @var $value ... */
partout dans vos fichiers de code (par exemple dans les boucles), comme Zahymaka l'a confirmé avec sa réponse. Votre utilisateur d'API n'est pas obligé d'introduire ces docblocks pour que le code soit complété. Avoir @return sur un seul endroit réduit la redondance (@var) le plus possible. Saupoudrer "docBlocks avec @var" rendrait votre code le moins lisible.
Finalement, vous avez terminé. Semble difficile à atteindre? On dirait de prendre un marteau pour casser une noix? Pas vraiment, puisque vous êtes familier avec ces interfaces et avec du code propre. Rappelez-vous: votre code source est écrit une fois / lu plusieurs.
Si l'achèvement du code de votre IDE ne fonctionne pas avec cette approche, passez à une meilleure (par exemple IntelliJ IDEA, PhpStorm, Netbeans) ou déposez une demande de fonctionnalité sur le suivi des problèmes de votre producteur IDE.
Merci à Christian Weiss (d'Allemagne) d'avoir été mon entraîneur et de m'avoir enseigné un truc tellement génial. PS: Rencontrez-moi et lui sur XING.