Treat a lone @see tag the same way as a lone {@inheritDoc}

As explained by @mvriel, Doctrine and Symfony introduced the meaning of a lone {@inheritDoc} as "inherit all information from the parent element". #37 suggests to introduce a @inheritDoc block tag to do basically the same.

A better (possibly additional) solution might be to use a lone @see block tag instead. Many IDE's don't really understand {@inheritDoc} and it usually isn't possible to navigate to or to see the inherited documentation when a method is viewed. You usually have to scroll to the top of the file, click on the parent class name, search for the method or further traverse up in the class tree.

A lone @see block tag is a elegant solution for this problem: Many IDE's understand this very generic DocBlock tag and make it clickable. A developer can now simply click on the @see block tag and immediately navigates to the desired DocBlock.

This also resolves #79 and #128.

A subject for debate might be what class should be referenced - must it be the parent class, the first parent class which actually specifies a non-inherited DocBlock or should this be subject to the developers wish? IMHO it usually should reference the first parent class with a non-inherited DocBlock, but a developer should choose this at his convenience.

phpDocumentor (as reference implementation) should make sure that the @see block tag is the only tag of the method's DocBlock. It should also validate that the referenced class is one of the parent classes, one of the implemented interfaces or a used trait. In this case phpDocumentor shouldn't output warnings about the missing DocBlock. In somewhat vague situations (e.g. when multiple interfaces or traits implement a method), the @see block tag should be used to determine which DocBlock is inherited.

class Foo {
    /**
     * This is a example method.
     *
     * @param string $foo The example parameter.
     * @return void
     */
    public function example($foo)
    {
        // do something
    }
}

class Bar extends Foo {
    /**
     * @see Foo::example()
     */
    public function example($foo)
    {
        parent::example($foo);
        // do some more
    }
}

@see parent::example() should be valid, too.

phpDocumentor / fig-standards

Treat a lone @see tag the same way as a lone {@inheritDoc} #132