WARNING: THIS SITE IS A MIRROR OF GITHUB.COM / IT CANNOT LOGIN OR REGISTER ACCOUNTS / THE CONTENTS ARE PROVIDED AS-IS / THIS SITE ASSUMES NO RESPONSIBILITY FOR ANY DISPLAYED CONTENT OR LINKS / IF YOU FOUND SOMETHING MAY NOT GOOD FOR EVERYONE, CONTACT ADMIN AT ilovescratch@foxmail.com
Skip to content

Commit 453a7f8

Browse files
mspirkovmspirkov
authored
Fix #348: Inherit descriptions of the parent class
1 parent 81990bd commit 453a7f8

24 files changed

+338
-29
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Yii Framework 2 apidoc extension Change Log
1313
- Enh #342: Remove unnecessary files from Composer package (mspirkov)
1414
- Enh #341: Add support for nullable types (mspirkov)
1515
- Enh #347: Add PHPDoc types for class properties (mspirkov)
16+
- Enh #348: Inherit descriptions of the parent class (mspirkov)
1617

1718

1819
3.0.8 November 24, 2025

‎models/BaseDoc.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ class BaseDoc extends BaseObject
4343
private const PHPSTAN_IMPORT_TYPE_ANNOTATION_NAME = 'phpstan-import-type';
4444
private const PSALM_IMPORT_TYPE_ANNOTATION_NAME = 'psalm-import-type';
4545

46-
private const INHERITDOC_TAG_NAME = 'inheritdoc';
46+
public const INHERITDOC_TAG_NAME = 'inheritdoc';
4747
private const TODO_TAG_NAME = 'todo';
4848

4949
/**

‎models/Context.php‎

Lines changed: 67 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
namespace yii\apidoc\models;
1010

11+
use phpDocumentor\Reflection\DocBlock\Tag;
12+
use phpDocumentor\Reflection\DocBlock\Tags\BaseTag;
1113
use phpDocumentor\Reflection\DocBlockFactory;
1214
use phpDocumentor\Reflection\File\LocalFile;
1315
use phpDocumentor\Reflection\Php\Factory\ClassConstant as ClassConstantFactory;
@@ -283,9 +285,27 @@ protected function updateSubInterfaceInheritance($interface)
283285
*/
284286
protected function inheritDocs($class)
285287
{
288+
if ($class->hasTag(BaseDoc::INHERITDOC_TAG_NAME)) {
289+
$inheritTag = $class->getFirstTag(BaseDoc::INHERITDOC_TAG_NAME);
290+
$parentClass = $this->classes[$class->parentClass] ?? null;
291+
if ($inheritTag !== null && $parentClass !== null) {
292+
$class->shortDescription = $parentClass->shortDescription;
293+
$class->description = $this->inheritDescription(
294+
$class->description,
295+
$parentClass->description,
296+
$inheritTag,
297+
);
298+
299+
$class->removeTag(BaseDoc::INHERITDOC_TAG_NAME);
300+
}
301+
}
302+
286303
// inherit for properties
287304
foreach ($class->properties as $p) {
288-
if ($p->hasTag('inheritdoc') && ($inheritTag = $p->getFirstTag('inheritdoc')) !== null) {
305+
if (
306+
$p->hasTag(BaseDoc::INHERITDOC_TAG_NAME)
307+
&& ($inheritTag = $p->getFirstTag(BaseDoc::INHERITDOC_TAG_NAME)) !== null
308+
) {
289309
$inheritedProperty = $this->inheritPropertyRecursive($p, $class);
290310
if (!$inheritedProperty) {
291311
$this->errors[] = [
@@ -307,19 +327,22 @@ protected function inheritDocs($class)
307327
}
308328
}
309329
// descriptions will be concatenated.
310-
$p->description = implode("\n\n", [
311-
trim($p->description),
312-
trim($inheritedProperty->description),
313-
$inheritTag->getDescription(),
314-
]);
330+
$p->description = $this->inheritDescription(
331+
$p->description,
332+
$inheritedProperty->description,
333+
$inheritTag
334+
);
315335

316-
$p->removeTag('inheritdoc');
336+
$p->removeTag(BaseDoc::INHERITDOC_TAG_NAME);
317337
}
318338
}
319339

320340
// inherit for methods
321341
foreach ($class->methods as $m) {
322-
if ($m->hasTag('inheritdoc') && ($inheritTag = $m->getFirstTag('inheritdoc')) !== null) {
342+
if (
343+
$m->hasTag(BaseDoc::INHERITDOC_TAG_NAME)
344+
&& ($inheritTag = $m->getFirstTag(BaseDoc::INHERITDOC_TAG_NAME)) !== null
345+
) {
323346
$inheritedMethod = $this->inheritMethodRecursive($m, $class);
324347
if (!$inheritedMethod) {
325348
$this->errors[] = [
@@ -340,11 +363,11 @@ protected function inheritDocs($class)
340363
}
341364
}
342365
// descriptions will be concatenated.
343-
$m->description = implode("\n\n", [
344-
trim($m->description),
345-
trim($inheritedMethod->description),
346-
$inheritTag->getDescription(),
347-
]);
366+
$m->description = $this->inheritDescription(
367+
$m->description,
368+
$inheritedMethod->description,
369+
$inheritTag,
370+
);
348371

349372
foreach ($m->params as $i => $param) {
350373
if (!isset($inheritedMethod->params[$i])) {
@@ -362,18 +385,19 @@ protected function inheritDocs($class)
362385
$param->type = $inheritedMethod->params[$i]->type;
363386
}
364387
}
365-
$m->removeTag('inheritdoc');
388+
$m->removeTag(BaseDoc::INHERITDOC_TAG_NAME);
366389
}
367390
}
368391
}
369392

370393
/**
371394
* @param MethodDoc $method
372395
* @param ClassDoc $class
373-
* @return mixed
396+
* @return MethodDoc|false
374397
*/
375398
private function inheritMethodRecursive($method, $class)
376399
{
400+
/** @var (ClassDoc|InterfaceDoc)[] */
377401
$inheritanceCandidates = array_merge(
378402
$this->getParents($class),
379403
$this->getInterfaces($class),
@@ -383,7 +407,7 @@ private function inheritMethodRecursive($method, $class)
383407
foreach ($inheritanceCandidates as $candidate) {
384408
if (isset($candidate->methods[$method->name])) {
385409
$cmethod = $candidate->methods[$method->name];
386-
if (!$candidate instanceof InterfaceDoc && $cmethod->hasTag('inheritdoc')) {
410+
if (!$candidate instanceof InterfaceDoc && $cmethod->hasTag(BaseDoc::INHERITDOC_TAG_NAME)) {
387411
$this->inheritDocs($candidate);
388412
}
389413
$methods[] = $cmethod;
@@ -396,10 +420,11 @@ private function inheritMethodRecursive($method, $class)
396420
/**
397421
* @param PropertyDoc $method
398422
* @param ClassDoc $class
399-
* @return mixed
423+
* @return PropertyDoc|false
400424
*/
401425
private function inheritPropertyRecursive($method, $class)
402426
{
427+
/** @var (ClassDoc|InterfaceDoc)[] */
403428
$inheritanceCandidates = array_merge(
404429
$this->getParents($class),
405430
$this->getInterfaces($class),
@@ -409,7 +434,7 @@ private function inheritPropertyRecursive($method, $class)
409434
foreach ($inheritanceCandidates as $candidate) {
410435
if (isset($candidate->properties[$method->name])) {
411436
$cproperty = $candidate->properties[$method->name];
412-
if ($cproperty->hasTag('inheritdoc')) {
437+
if ($cproperty->hasTag(BaseDoc::INHERITDOC_TAG_NAME)) {
413438
$this->inheritDocs($candidate);
414439
}
415440
$properties[] = $cproperty;
@@ -421,7 +446,7 @@ private function inheritPropertyRecursive($method, $class)
421446

422447
/**
423448
* @param ClassDoc $class
424-
* @return array
449+
* @return ClassDoc[]
425450
*/
426451
private function getParents($class)
427452
{
@@ -433,7 +458,7 @@ private function getParents($class)
433458

434459
/**
435460
* @param ClassDoc $class
436-
* @return array
461+
* @return InterfaceDoc[]
437462
*/
438463
private function getInterfaces($class)
439464
{
@@ -596,4 +621,26 @@ public function getReflectionProject()
596621

597622
return $project;
598623
}
624+
625+
private function inheritDescription(
626+
?string $currentDescription,
627+
?string $parentDescription,
628+
Tag $inheritTag
629+
): string {
630+
$result = $currentDescription ?? '';
631+
632+
$parentDescription = trim((string) $parentDescription);
633+
if ($parentDescription !== '') {
634+
$result .= "\n\n" . $parentDescription;
635+
}
636+
637+
if ($inheritTag instanceof BaseTag) {
638+
$inheritTagDescription = trim((string) $inheritTag->getDescription());
639+
if ($inheritTagDescription !== '') {
640+
$result .= "\n\n" . $inheritTagDescription;
641+
}
642+
}
643+
644+
return trim($result);
645+
}
599646
}

‎phpstan-baseline.neon‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,6 @@ parameters:
2020
count: 1
2121
path: renderers/BaseRenderer.php
2222

23-
-
24-
message: "#^Call to an undefined method phpDocumentor\\\\Reflection\\\\DocBlock\\\\Tag\\:\\:getDescription\\(\\)\\.$#"
25-
count: 2
26-
path: models/Context.php
27-
2823
-
2924
message: "#^Property yii\\\\apidoc\\\\models\\\\ClassDoc\\:\\:\\$events \\(array\\<yii\\\\apidoc\\\\models\\\\EventDoc\\>\\) does not accept array\\<yii\\\\apidoc\\\\models\\\\ConstDoc\\|yii\\\\apidoc\\\\models\\\\MethodDoc\\|yii\\\\apidoc\\\\models\\\\PropertyDoc\\>\\.$#"
3025
count: 1

‎tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__10.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
<a class="list-group-item" data-toggle="collapse" data-parent="#navigation">yiiunit\apidoc\data\api\web <b class="caret"></b></a><div class="submenu panel-collapse collapse">
6363
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetbundle.html">AssetBundle</a>
6464
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetmanager.html">AssetManager</a>
65+
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-erroraction.html">ErrorAction</a>
6566
</div>
6667
</div> </div>
6768
<div class="col-md-9 api-content" role="main">

‎tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__11.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
<a class="list-group-item" data-toggle="collapse" data-parent="#navigation">yiiunit\apidoc\data\api\web <b class="caret"></b></a><div class="submenu panel-collapse collapse">
6363
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetbundle.html">AssetBundle</a>
6464
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetmanager.html">AssetManager</a>
65+
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-erroraction.html">ErrorAction</a>
6566
</div>
6667
</div> </div>
6768
<div class="col-md-9 api-content" role="main">

‎tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__12.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
<a class="list-group-item" data-toggle="collapse" data-parent="#navigation">yiiunit\apidoc\data\api\web <b class="caret"></b></a><div class="submenu panel-collapse collapse">
6363
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetbundle.html">AssetBundle</a>
6464
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetmanager.html">AssetManager</a>
65+
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-erroraction.html">ErrorAction</a>
6566
</div>
6667
</div> </div>
6768
<div class="col-md-9 api-content" role="main">

‎tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__13.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
<a class="list-group-item" data-toggle="collapse" data-parent="#navigation">yiiunit\apidoc\data\api\web <b class="caret"></b></a><div class="submenu panel-collapse collapse">
6363
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetbundle.html">AssetBundle</a>
6464
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetmanager.html">AssetManager</a>
65+
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-erroraction.html">ErrorAction</a>
6566
</div>
6667
</div> </div>
6768
<div class="col-md-9 api-content" role="main">

‎tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__14.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
<a class="list-group-item" data-toggle="collapse" data-parent="#navigation">yiiunit\apidoc\data\api\web <b class="caret"></b></a><div class="submenu panel-collapse collapse">
6363
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetbundle.html">AssetBundle</a>
6464
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetmanager.html">AssetManager</a>
65+
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-erroraction.html">ErrorAction</a>
6566
</div>
6667
</div> </div>
6768
<div class="col-md-9 api-content" role="main">

‎tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__15.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
<a class="list-group-item" data-toggle="collapse" data-parent="#navigation">yiiunit\apidoc\data\api\web <b class="caret"></b></a><div class="submenu panel-collapse collapse">
6363
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetbundle.html">AssetBundle</a>
6464
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-assetmanager.html">AssetManager</a>
65+
<a class="list-group-item" href="./yiiunit-apidoc-data-api-web-erroraction.html">ErrorAction</a>
6566
</div>
6667
</div> </div>
6768
<div class="col-md-9 api-content" role="main">

0 commit comments

Comments
 (0)