Prefiro ler e escrever código limpo - conforme descrito em "Código Limpo", de Robert C. Martin. Ao seguir o seu credo, você não deve exigir que o desenvolvedor (como usuário da sua API) conheça a estrutura (interna) da sua matriz.
O usuário da API pode perguntar: Isso é uma matriz com apenas uma dimensão? Os objetos estão espalhados em todos os níveis de uma matriz multidimensional? Quantos loops aninhados (foreach, etc.) eu preciso acessar todos os objetos? Que tipo de objetos são "armazenados" nessa matriz?
Como você descreveu, deseja usar essa matriz (que contém objetos) como uma matriz unidimensional.
Conforme descrito por Nishi, você pode usar:
/**
* @return SomeObj[]
*/
por isso.
Mais uma vez: esteja ciente - essa não é uma notação padrão de bloqueio de documentos. Essa notação foi introduzida por alguns produtores de IDE.
Ok, ok, como desenvolvedor, você sabe que "[]" está vinculado a uma matriz em PHP. Mas o que um "algo []" significa no contexto normal do PHP? "[]" significa: crie um novo elemento dentro de "algo". O novo elemento pode ser tudo. Mas o que você deseja expressar é: matriz de objetos do mesmo tipo e do tipo exato. Como você pode ver, o produtor do IDE introduz um novo contexto. Um novo contexto que você teve que aprender. Um novo contexto que outros desenvolvedores de PHP tiveram que aprender (para entender seus docblocks). Estilo ruim (!).
Como sua matriz possui uma dimensão, talvez você queira chamar essa "matriz de objetos" de "lista". Esteja ciente de que "lista" tem um significado muito especial em outras linguagens de programação. Seria melhor chamar isso de "coleção", por exemplo.
Lembre-se: você usa uma linguagem de programação que permite todas as opções de OOP. Use uma classe em vez de uma matriz e torne sua classe percorrível como uma matriz. Por exemplo:
class orderCollection implements ArrayIterator
Ou se você deseja armazenar os objetos internos em diferentes níveis em uma estrutura de matriz / objeto multidimensional:
class orderCollection implements RecursiveArrayIterator
Esta solução substitui sua matriz por um objeto do tipo "orderCollection", mas não habilita a conclusão de código no seu IDE até o momento. OK. Próxima Etapa:
Implemente os métodos introduzidos pela interface com docblocks - em particular:
/**
* [...]
* @return Order
*/
orderCollection::current()
/**
* [...]
* @return integer E.g. database identifier of the order
*/
orderCollection::key()
/**
* [...]
* @return Order
*/
orderCollection::offsetGet()
Não se esqueça de usar dicas de tipo para:
orderCollection::append(Order $order)
orderCollection::offsetSet(Order $order)
Esta solução para de introduzir muitos:
/** @var $key ... */
/** @var $value ... */
em todos os seus arquivos de código (por exemplo, dentro de loops), como Zahymaka confirmou com sua resposta. O usuário da API não é obrigado a introduzir os docblocks, a ter o código completo. Ter @return em apenas um local reduz a redundância (@var) o mais mutch possível. Polvilhe "docBlocks com @var" para tornar seu código mais legível.
Finalmente você está pronto. Parece difícil de conseguir? Parece tomar uma marreta para quebrar uma noz? Não muito, desde que você esteja familiarizado com essas interfaces e com o código limpo. Lembre-se: seu código-fonte é escrito uma vez / é lido muitos.
Se a conclusão do código do seu IDE não funcionar com essa abordagem, mude para uma melhor (por exemplo, IntelliJ IDEA, PhpStorm, Netbeans) ou envie uma solicitação de recurso no rastreador de problemas do seu produtor de IDE.
Agradeço a Christian Weiss (da Alemanha) por ser meu treinador e por me ensinar coisas excelentes. PS: Encontre eu e ele no XING.