From 52097568588e60618c86626fd05ee42e1ed4e64a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D0=BA=D1=81=D0=B8=D0=BC=20=D0=A1=D0=BF=D0=B8?= =?UTF-8?q?=D1=80=D0=BA=D0=BE=D0=B2?= Date: Mon, 24 Nov 2025 14:35:00 +0400 Subject: [PATCH 1/4] Log invalid tags --- models/BaseDoc.php | 18 ++++- tests/commands/ApiControllerTest.php | 3 + ...trollerTest__testGenerateBootstrap__3.html | 49 ++++++++++++++ ...ntrollerTest__testGenerateBootstrap__5.txt | 66 +++++++++++++++++++ ...ntrollerTest__testGenerateBootstrap__6.txt | 10 +++ tests/data/api/animal/Dog.php | 7 ++ 6 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt create mode 100644 tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt diff --git a/models/BaseDoc.php b/models/BaseDoc.php index 10854a0..5be9abd 100644 --- a/models/BaseDoc.php +++ b/models/BaseDoc.php @@ -1,4 +1,5 @@ getName() === self::TODO_TAG_NAME) { $this->todos[] = $tag; unset($this->tags[$i]); + } elseif ($tag instanceof InvalidTag && $context !== null) { + $exception = $tag->getException(); + $message = 'Invalid tag: ' . $tag->render() . '.'; + + if ($exception !== null) { + $message .= ' Exception message: ' . $exception->getMessage(); + } + + $context->errors[] = [ + 'line' => $this->startLine, + 'file' => $this->sourceFile, + 'message' => $message, + ]; } } @@ -242,7 +257,8 @@ public static function extractFirstSentence($text, $prevText = '') if ($length >= $pos + 2) { $abbrev = mb_substr($text, $pos - 3, 4, 'utf-8'); // do not break sentence after abbreviation - if ($abbrev === 'e.g.' || + if ( + $abbrev === 'e.g.' || $abbrev === 'i.e.' || mb_substr_count($prevText, '`', 'utf-8') % 2 === 1 ) { diff --git a/tests/commands/ApiControllerTest.php b/tests/commands/ApiControllerTest.php index 97f3352..128f365 100644 --- a/tests/commands/ApiControllerTest.php +++ b/tests/commands/ApiControllerTest.php @@ -99,5 +99,8 @@ public function testGenerateBootstrap() $sourceFilesCount = count(FileHelper::findFiles($sourceFilesDir, ['recursive' => true])); $this->assertSame($sourceFilesCount, $filesCount); + + $this->assertMatchesTextSnapshot(file_get_contents("{$outputPath}/warnings.txt")); + $this->assertMatchesTextSnapshot(file_get_contents("{$outputPath}/errors.txt")); } } diff --git a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__3.html b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__3.html index 93e8e75..7103650 100644 --- a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__3.html +++ b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__3.html @@ -166,6 +166,11 @@

Public Methods

isOlder() Checks whether the animal is older than the specified time. yiiunit\apidoc\data\api\animal\Animal + + + methodWithInvalidReturnTag() + + yiiunit\apidoc\data\api\animal\Dog render() @@ -406,6 +411,50 @@

Method Details

{ return$this->getAge() > $date; } + + + + + + +
+
+ + + + methodWithInvalidReturnTag() + + + public method + +
+ + +
+ +

+
+ + + + +
+publicmixedmethodWithInvalidReturnTag ( )
+ + + + +

+ +

+
+
+ 
+                publicfunctionmethodWithInvalidReturnTag()
+{
+}
diff --git a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt new file mode 100644 index 0000000..e353c47 --- /dev/null +++ b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt @@ -0,0 +1,66 @@ +Array +( + [0] => Array + ( + [line] => 41 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [message] => No docblock for element '$propertyWithoutDoc' + ) + + [1] => Array + ( + [line] => 41 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [message] => No short description for element '$propertyWithoutDoc' + ) + + [2] => Array + ( + [line] => 43 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [message] => No docblock for element '$propertyWithoutDocAndTypeHint' + ) + + [3] => Array + ( + [line] => 43 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [message] => No short description for element '$propertyWithoutDocAndTypeHint' + ) + + [4] => Array + ( + [line] => 70 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [message] => No docblock for element 'setBirthDate' + ) + + [5] => Array + ( + [line] => 32 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Cat.php + [message] => No docblock for element 'methodWithoutDocAndTypeHints' + ) + + [6] => Array + ( + [line] => 40 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Cat.php + [message] => No short description for Method 'methodWithTodoTag' + ) + + [7] => Array + ( + [line] => 30 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Dog.php + [message] => No short description for Method 'methodWithInvalidReturnTag' + ) + + [8] => Array + ( + [line] => 11 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/base/Component.php + [message] => No docblock for element 'yiiunit\apidoc\data\api\base\Component' + ) + +) diff --git a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt new file mode 100644 index 0000000..b6f3f33 --- /dev/null +++ b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt @@ -0,0 +1,10 @@ +Array +( + [0] => Array + ( + [line] => 30 + [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Dog.php + [message] => Invalid tag: @return invalid-type. Exception message: "\yiiunit\apidoc\data\api\animal\invalid-type" is not a valid Fqsen. + ) + +) diff --git a/tests/data/api/animal/Dog.php b/tests/data/api/animal/Dog.php index 9bf8c81..6752a83 100644 --- a/tests/data/api/animal/Dog.php +++ b/tests/data/api/animal/Dog.php @@ -23,4 +23,11 @@ public function render() // this method has `inheritdoc` tag without brackets return 'This is a dog'; } + + /** + * @return invalid-type + */ + public function methodWithInvalidReturnTag() + { + } } From e721be4d2ffb9c9a560e8d49ce9b3f225e1bfb2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D0=BA=D1=81=D0=B8=D0=BC=20=D0=A1=D0=BF=D0=B8?= =?UTF-8?q?=D1=80=D0=BA=D0=BE=D0=B2?= Date: Mon, 24 Nov 2025 14:46:18 +0400 Subject: [PATCH 2/4] fix tests --- tests/commands/ApiControllerTest.php | 11 +++++++++-- ...ontrollerTest__testGenerateBootstrap__5.txt | 18 +++++++++--------- ...ontrollerTest__testGenerateBootstrap__6.txt | 2 +- 3 files changed, 19 insertions(+), 12 deletions(-) diff --git a/tests/commands/ApiControllerTest.php b/tests/commands/ApiControllerTest.php index 128f365..627f76d 100644 --- a/tests/commands/ApiControllerTest.php +++ b/tests/commands/ApiControllerTest.php @@ -100,7 +100,14 @@ public function testGenerateBootstrap() $this->assertSame($sourceFilesCount, $filesCount); - $this->assertMatchesTextSnapshot(file_get_contents("{$outputPath}/warnings.txt")); - $this->assertMatchesTextSnapshot(file_get_contents("{$outputPath}/errors.txt")); + $warningsContent = file_get_contents("{$outputPath}/warnings.txt"); + // Remove the dynamic parts of the paths to the files + $warningsContent = preg_replace('/(\s*\[file\] => ).*(\/tests\/.*\.php)/', '$1$2', $warningsContent); + $this->assertMatchesTextSnapshot($warningsContent); + + $errorsContent = file_get_contents("{$outputPath}/errors.txt"); + // Remove the dynamic parts of the paths to the files + $errorsContent = preg_replace('/(\s*\[file\] => ).*(\/tests\/.*\.php)/', '$1$2', $errorsContent); + $this->assertMatchesTextSnapshot($errorsContent); } } diff --git a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt index e353c47..f688c1b 100644 --- a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt +++ b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt @@ -3,63 +3,63 @@ Array [0] => Array ( [line] => 41 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [file] => /tests/data/api/animal/Animal.php [message] => No docblock for element '$propertyWithoutDoc' ) [1] => Array ( [line] => 41 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [file] => /tests/data/api/animal/Animal.php [message] => No short description for element '$propertyWithoutDoc' ) [2] => Array ( [line] => 43 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [file] => /tests/data/api/animal/Animal.php [message] => No docblock for element '$propertyWithoutDocAndTypeHint' ) [3] => Array ( [line] => 43 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [file] => /tests/data/api/animal/Animal.php [message] => No short description for element '$propertyWithoutDocAndTypeHint' ) [4] => Array ( [line] => 70 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Animal.php + [file] => /tests/data/api/animal/Animal.php [message] => No docblock for element 'setBirthDate' ) [5] => Array ( [line] => 32 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Cat.php + [file] => /tests/data/api/animal/Cat.php [message] => No docblock for element 'methodWithoutDocAndTypeHints' ) [6] => Array ( [line] => 40 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Cat.php + [file] => /tests/data/api/animal/Cat.php [message] => No short description for Method 'methodWithTodoTag' ) [7] => Array ( [line] => 30 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Dog.php + [file] => /tests/data/api/animal/Dog.php [message] => No short description for Method 'methodWithInvalidReturnTag' ) [8] => Array ( [line] => 11 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/base/Component.php + [file] => /tests/data/api/base/Component.php [message] => No docblock for element 'yiiunit\apidoc\data\api\base\Component' ) diff --git a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt index b6f3f33..f939d78 100644 --- a/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt +++ b/tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt @@ -3,7 +3,7 @@ Array [0] => Array ( [line] => 30 - [file] => /home/mspirkov/open-source/yiisoft/yii2-apidoc/tests/data/api/animal/Dog.php + [file] => /tests/data/api/animal/Dog.php [message] => Invalid tag: @return invalid-type. Exception message: "\yiiunit\apidoc\data\api\animal\invalid-type" is not a valid Fqsen. ) From 8e5c4a18cb142cb8966169f295162ce8b9df2c57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D0=BA=D1=81=D0=B8=D0=BC=20=D0=A1=D0=BF=D0=B8?= =?UTF-8?q?=D1=80=D0=BA=D0=BE=D0=B2?= Date: Mon, 24 Nov 2025 14:47:59 +0400 Subject: [PATCH 3/4] comment --- tests/commands/ApiControllerTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/commands/ApiControllerTest.php b/tests/commands/ApiControllerTest.php index 627f76d..c15b776 100644 --- a/tests/commands/ApiControllerTest.php +++ b/tests/commands/ApiControllerTest.php @@ -101,12 +101,12 @@ public function testGenerateBootstrap() $this->assertSame($sourceFilesCount, $filesCount); $warningsContent = file_get_contents("{$outputPath}/warnings.txt"); - // Remove the dynamic parts of the paths to the files + // Remove the dynamic parts of the file paths $warningsContent = preg_replace('/(\s*\[file\] => ).*(\/tests\/.*\.php)/', '$1$2', $warningsContent); $this->assertMatchesTextSnapshot($warningsContent); $errorsContent = file_get_contents("{$outputPath}/errors.txt"); - // Remove the dynamic parts of the paths to the files + // Remove the dynamic parts of the file paths $errorsContent = preg_replace('/(\s*\[file\] => ).*(\/tests\/.*\.php)/', '$1$2', $errorsContent); $this->assertMatchesTextSnapshot($errorsContent); } From 569b5ba9ff03930d6baa03333318133d40e0a315 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D0=BA=D1=81=D0=B8=D0=BC=20=D0=A1=D0=BF=D0=B8?= =?UTF-8?q?=D1=80=D0=BA=D0=BE=D0=B2?= Date: Mon, 24 Nov 2025 14:48:43 +0400 Subject: [PATCH 4/4] changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 42738c5..4cc7e4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ Yii Framework 2 apidoc extension Change Log 3.0.9 under development ----------------------- -- no changes in this release. +- Enh #337: Log invalid tags (mspirkov) 3.0.8 November 24, 2025