WordPress DocBlock: inheritdoc should be supported

[killua99]

The DocBlock for decorators or classes that use interfaces for document a function normally is use;

/**
 * @inheritdoc
 */
public function save() { ... }

[rilwis]

+1. Love to see this implemented, since it reduces a lot of comments when the plugin uses many inheritance.

[IreneStr]

We run into this as well. We got a lot of warnings about missing short descriptions where we're using @inheritDoc.

[jrfnl]

Unfortunately that's not reliably sniffable.

PHPCS scans files in an undetermined order and possibly in parallel when parallel scanning is enabled.

To be able to make exceptions for specific methods declared in interfaces we'd need to know in advance which methods are declared in which interface, as @inheritdoc should only be allowed for those specific methods.

Unfortunately we don't have access to that information at the start of the scan.
We could keep a cache of information building this up during the scan, but at any point in time, this cache will be incomplete and possibly unreliable with parallel scanning.
And even then, this cache would be incomplete in most cases, as you would normally not scan your vendor dependencies, while implementing an interface defined in one of those dependencies is quite common.

Allowing just any method in a class which implements to use @inheritdoc will result in a lot of missing documentation, so is something I would strongly discourage.

[killua99]

I guess you are mixing concepts here.

You could write this on a method

class myClass implements theValueOfX { 
/**
 * Something that doesn't represent documentation.
 */ 
public function getTheValueOfX() { ... }
}

That PHP CS will pass without any issue. Still is missing documentation.

You're mixing what the writer writes and what a functionality does. Using @inheritDoc is not equal missing documentation, is the other way around is not causing more duplication or alteration on the documentation.

[jrfnl]

@killua99 Whether something is good or bad documentation is a whole other matter and most definitely outside of the scope of WPCS.

Using @inheritdoc is not equal missing documentation

It is when the method isn't inherited...

[killua99]

But, who is gonna use it, if the method isn't inherited? I mean, the word is self describing inherit Documentation, from where is gonna inherit if is not an inherited method?

That was my point perhaps I didn't explain me well.

You can't control what the code writer writes. If he place a wrong DocBlock on a method then how are you gonna control it anyway? Is the same as using this @inheritDoc outside an inherit method. I'm with you, is wrong to use it outside an inheritDoc but on the case of inheritDoc like interfaces, abstraction etc ... is the right way of doing it.

[jrfnl]

@killua99 I'm not saying using @inheritDoc is wrong in the right circumstances. It's not.

All I'm saying is that within the constraints of using static analysis it is not easily possible to make an exception for it in a reliable manner.

[killua99]

Perhaps this is too old and not relevant. Feel free to close this issue