title: PHPStorm: correct PHPDoc for a Collection of Objects?
body: <p>I'm using the <a href="http://www.jetbrains.com/phpstorm/" rel="nofollow noreferrer">PHPStorm</a> IDE, and run into trouble when I run the code inspection.</p>
  <p>I have a method which returns a collection of objects. The <code>Collection</code> itself is an object, which has its own methods, and implements the <a href="http://php.net/manual/en/class.traversable.php" rel="nofollow noreferrer">Traversable</a> interface:</p>
  
  <pre class="lang-php prettyprint-override"><code>class Repository
  {
      public function findByCustomer(Customer $user)
      {
          // ...
          return new Collection($orders);
      }
  }
  </code></pre>
  <p>If I document <code>findByUser()</code> to return a <code>Collection</code>, the code inspection understands the methods on this object, but doesn't understand what objects the collection contains:</p>
  <pre class="lang-php prettyprint-override"><code>/**
   * @return Collection
   */
  public function findByCustomer() { ... }
  </code></pre>
  <p><img src="https://i.stack.imgur.com/8pfDj.png" alt="Method getTotal() not found in class Collection" /></p>
  <p>If I document <code>findByUser()</code> to return a collection of <code>Order</code> objects, the code inspection now understands what's inside the collection, but not the methods on the <code>Collection</code> itself:</p>
  <pre class="lang-php prettyprint-override"><code>/**
   * @return Order[]
   */
  public function findByCustomer() { ... }
  </code></pre>
  <p><img src="https://i.stack.imgur.com/ZTFSU.png" alt="Method slice() not found in class Order[]" /></p>
  <p>Is there a way to specify both at the same time, something like Java's syntax?</p>
  <pre class="lang-php prettyprint-override"><code>/**
   * @return Collection&lt;Order&gt;
   */
  public function findByCustomer() { ... }
  </code></pre>