Provide support for `{@inheritdoc}` parsing

[klimov-paul]

What steps will reproduce the problem?

Declare code using 'inheritdoc' tag with brackets, e.g. {@inheritdoc} :

/**
 * {@inheritdoc}
 */
public function method();

Generate API doc for this code

What's expected?

Description inherited from the parent's code/

What do you get instead?

Description displays {@inheritdoc} string.

Additional info

See yiisoft/yii2#11635

Q	A
Yii vesion	2.0.13
Yii APIDoc version	2.1.0
PHP version	*
Operating system	CentOS

[klimov-paul]

The reason of incorrect parsing is outdated vresion of "phpdocumentor/reflection-docblock" library.
Its modern version even uses {@inheritdoc} for own classes:
https://github.com/phpDocumentor/ReflectionDocBlock/blob/3.3.2/src/DocBlock/Tags/PropertyRead.php#L50-L53

However upgrade is problematic, since there is stable release "phpdocumentor/reflection", which can use "phpdocumentor/reflection-docblock" higher then 2.x.

[klimov-paul]

Resolved by commit a42bd9b

[samdark]

I think you're missing some cases: yiisoft/yii2#11635 (comment)

[klimov-paul]

I can see no cases missing.
If there is a problem in tags merging from parent doc block and child's one using @inheritdoc - it is a separated issue. Fix does not affect it.

[samdark]

I mean

This class decorates BaseClass.

{@inheritdoc}

Note: xxx

Should replace the middle part but use surrounding strings as well.

[klimov-paul]

This I can not fix. Although I haven't heard any complain on such case.
The original issue is about following cases:

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

/**
 * {@inheritdoc}
 * @return Override
 */
public function foo() {..}

/**
 * {@inheritdoc}
 * @param Override $var
 */
public function foo($var) {..}

which should be supported as following:

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

/**
 * @inheritdoc
 * @return Override
 */
public function foo() {..}

/**
 * @inheritdoc
 * @param Override $var
 */
public function foo($var) {..}

Until the fix provided here any occurance of {@inheritdoc} (in brackets) was simply ignored (unparsed). Now it is fixed.
If there is a demand for inserting of {@inheritdoc} in the plain text description - it should be handled as separated issue, as its behavior is undertermined.

[samdark]

Yep. Let's not touch that till it's asked for.