Should @method augment inherited methods

[mvriel]

@cweiske pointed out the following scenario:

Given the code http://p.cweiske.de/49, he wanted to show in FooResponse's DocBlock what the correct return type would be. The best solution we could come up with was to have an @method call augment the inherited definifion.

Research should be done to see whether it is feasable and if so, implement it

[boenrobot]

IMHO, @method tags should be ADDED to whatever methods already exist. In other words, if a @method declares a method that exists in a parent, the generated docs should contain BOTH the docs of the parent and whatever @method declares.

This addresses the scenario, without potentially causing side effects (if by "augment" you mean "merge, with @method taken with a priority in cases of conflict").

[mvriel]

@ashnazg and I had discussed this idea on IRC and indeed; the gist is that @method should become part of the inheritance sequence if feasable with regards to performance.

This means that, given a sub and super class, that the chain of inheritance would be:

1. @method of superclass
2. method definition of superclass
3. @method definition of subclass
4. method definition of subclass

The same rules with regards to what gets inherited and what not will apply for the whole inheritence chain and do not need to change.

The above goes for properties as well

[boenrobot]

But consider a scenario where you have a real method... but you want to declare an alternative prototype that it may accept.

Take XSLTProcessor::setParameter() as an example. You'd want to have the first prototype being the "real" one (since it has the most arguments), but you'll also want to document the secondary prototype.

If either definition overrides the other one, you can't have both prototypes documented.

[mvriel]

That is an unsupported scenario at the moment and, at the moment, I think we should not solve that with the @method but with the actual method definition

[boenrobot]

So... maybe allow @method to appear on a real method's docs, where it would declare an alternative prototype/alias to that method?

[mvriel]

I don't know whether @method is the right tag for that, we should research if other languages have the same issue and how they deal with it

[jaapio]

Closing as this is just a discussion between maintainers. I didn't see any linked issues so I assume this isn't requested anymore after 11 years./