From b9938ac4bc03cd1b244931a1d611a49d0790717f Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Fri, 29 Nov 2024 12:01:11 +0400 Subject: [PATCH] feat(documentator): Deprecation mark output in generated help of `lara-asp-documentator:preprocess` command. --- .../documentator/docs/Commands/preprocess.md | 16 ++++---- .../documentator/src/Commands/Preprocess.php | 41 ++++++++++++++----- .../src/Commands/PreprocessTest.php | 16 ++++---- 3 files changed, 47 insertions(+), 26 deletions(-) diff --git a/packages/documentator/docs/Commands/preprocess.md b/packages/documentator/docs/Commands/preprocess.md index acb9ad43c..37c9ee369 100644 --- a/packages/documentator/docs/Commands/preprocess.md +++ b/packages/documentator/docs/Commands/preprocess.md @@ -59,8 +59,8 @@ run with default/normal level if it is not specified in its arguments. * `` - File path. * `` - additional parameters - * `summary`: `bool` = `true` - Include the class summary? * `description`: `bool` = `true` - Include the class description? + * `summary`: `bool` = `true` - Include the class summary? Includes the docblock of the first PHP class/interface/trait/enum/etc from `` file. Inline tags include as is except `@see`/`@link` @@ -72,16 +72,16 @@ which will be replaced to FQCN (if possible). Other tags are ignored. * `` - additional parameters * `depth`: `array|string|int|null` = `0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth) (eg the `0` means no nested directories, the `null` removes limits). - * `template`: `string` = `'default'` - Blade template. The documents passed in the `$data` ([`Data`][code-links/84d51020d324cc16]) - variable. Also, be careful with leading whitespaces. - * `order`: [`SortOrder`][code-links/7e5c66e8748c6ff8] = [`SortOrder::Asc`][code-links/08e0648f66e2d1a5] - Sort order. + * `include`: `array|string|null` = `null` - [Rules which filenames must match](https://symfony.com/doc/current/components/finder.html#path) + (only Markdown documents will be listed). * `level`: `?int` = `null` - Headings level. Possible values are * `null`: ` + 1` * `int`: explicit level (`1-6`) * `0`: `` - * `include`: `array|string|null` = `null` - [Rules which filenames must match](https://symfony.com/doc/current/components/finder.html#path) - (only Markdown documents will be listed). + * `order`: [`SortOrder`][code-links/7e5c66e8748c6ff8] = [`SortOrder::Asc`][code-links/08e0648f66e2d1a5] - Sort order. + * `template`: `string` = `'default'` - Blade template. The documents passed in the `$data` ([`Data`][code-links/84d51020d324cc16]) + variable. Also, be careful with leading whitespaces. Returns the list of `*.md` files in the `` directory. Each file must have `# Header` as the first construction. The first paragraph @@ -120,12 +120,12 @@ Includes the `` file. Includes the definition of the directive as a Markdown code block. -#### `[include:package-list]: ` +#### `[include:package-list]: ` 💀 * `` - Directory path. * `` - additional parameters - * `template`: `string` = `'default'` - Blade template. * `order`: [`SortOrder`][code-links/7e5c66e8748c6ff8] = [`SortOrder::Asc`][code-links/08e0648f66e2d1a5] - Sort order. + * `template`: `string` = `'default'` - Blade template. Generates package list from `` directory. The readme file will be used to determine package name and summary. diff --git a/packages/documentator/src/Commands/Preprocess.php b/packages/documentator/src/Commands/Preprocess.php index 137a82e9e..18885888a 100644 --- a/packages/documentator/src/Commands/Preprocess.php +++ b/packages/documentator/src/Commands/Preprocess.php @@ -17,6 +17,7 @@ use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Parameters; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Task as PreprocessTask; +use LastDragon_ru\LaraASP\Documentator\Utils\PhpDoc; use LastDragon_ru\LaraASP\Documentator\Utils\PhpDocumentFactory; use LastDragon_ru\LaraASP\Documentator\Utils\Text; use LastDragon_ru\LaraASP\Formatter\Formatter; @@ -54,7 +55,8 @@ description: 'Perform one or more task on the file.', )] class Preprocess extends Command { - public const Name = Package::Name.':preprocess'; + public const Name = Package::Name.':preprocess'; + private const DeprecationMarker = '💀'; /** * @phpcsSuppress SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint @@ -133,10 +135,11 @@ protected function getProcessedHelpTasks(int $level): string { $description = trim($this->getProcessedHelpTaskDescription($task, $level + 1)); $description = $description !== '' ? $description : $default; $extensions = '`'.implode('`, `', $task::getExtensions()).'`'; + $deprecated = $this->getDeprecatedMark(new ReflectionClass($task)); $title = trim((string) $this->getProcessedHelpTaskTitle($task)); $title = $title !== '' ? $title : "Task №{$index}"; $help .= <<getDocBlock($class, null, $level + 1); - $target = trim((string) $this->getProcessedHelpTaskPreprocessInstructionTarget($instruction, 'target', 2)); - $target = $target !== '' ? $target : '_No description provided_.'; - $params = $this->getProcessedHelpTaskPreprocessParameters($instruction, 'target', 2); + $class = new ReflectionClass($instruction); + $name = $instruction::getName(); + $desc = $this->getDocBlock($class, null, $level + 1); + $target = trim( + (string) $this->getProcessedHelpTaskPreprocessInstructionTarget($instruction, 'target', 2), + ); + $target = $target !== '' ? $target : '_No description provided_.'; + $params = $this->getProcessedHelpTaskPreprocessParameters($instruction, 'target', 2); + $deprecated = $this->getDeprecatedMark($class); if ($params !== null) { $help[$name] = rtrim( << ` + {$heading} `[{$name}]: `{$deprecated} * `` - {$target} * `` - additional parameters @@ -193,7 +199,7 @@ protected function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $ta } else { $help[$name] = rtrim( <<` + {$heading} `[{$name}]: `{$deprecated} * `` - {$target} @@ -288,6 +294,7 @@ protected function getProcessedHelpTaskPreprocessParameters( } // Add + $definition = $this->getDeprecatedMark($property).$definition; $description = trim($this->getDocBlock($property, $padding)); $description = $description !== '' ? $description : '_No description provided_.'; $parameters[trim($definition)] = $description; @@ -298,6 +305,9 @@ protected function getProcessedHelpTaskPreprocessParameters( return null; } + // Sort + ksort($parameters); + // Serialize $list = ''; @@ -346,4 +356,15 @@ private function getDocBlock( // Return return trim($help); } + + /** + * @param ReflectionClass|ReflectionProperty $object + */ + private function getDeprecatedMark(ReflectionClass|ReflectionProperty $object): string { + $comment = $object->getDocComment(); + $deprecated = $comment !== false && (new PhpDoc($comment))->isDeprecated(); + $deprecated = $deprecated ? ' '.self::DeprecationMarker : ''; + + return $deprecated; + } } diff --git a/packages/documentator/src/Commands/PreprocessTest.php b/packages/documentator/src/Commands/PreprocessTest.php index 69ad639f1..a583b795d 100644 --- a/packages/documentator/src/Commands/PreprocessTest.php +++ b/packages/documentator/src/Commands/PreprocessTest.php @@ -49,14 +49,14 @@ public function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $task, Target target target target target target target target target target target target target target target target target target. * `` - additional parameters - * `publicPropertyWithoutDefaultValue`: `int` - Description. - * `publicPropertyWithDefaultValue`: `float` = `123.0` - _No description provided_. - * `publicPropertyEnumWithDefaultValue`: `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum` = `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum::B` - _No description provided_. - * `publicPromotedPropertyWithoutDefaultValue`: `int` - Description. * `publicPromotedPropertyWithDefaultValue`: `int` = `321` - Summary. Description description description description description description description description description. + * `publicPromotedPropertyWithoutDefaultValue`: `int` - Description. + * `publicPropertyEnumWithDefaultValue`: `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum` = `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum::B` - _No description provided_. + * `publicPropertyWithDefaultValue`: `float` = `123.0` - _No description provided_. + * `publicPropertyWithoutDefaultValue`: `int` - Description. Summary summary summary. @@ -130,14 +130,14 @@ public function getProcessedHelpTaskPreprocessParameters( self::assertEquals( <<<'MARKDOWN' - * `publicPropertyWithoutDefaultValue`: `int` - Description. - * `publicPropertyWithDefaultValue`: `float` = `123.0` - _No description provided_. - * `publicPropertyEnumWithDefaultValue`: `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum` = `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum::B` - _No description provided_. - * `publicPromotedPropertyWithoutDefaultValue`: `int` - Description. * `publicPromotedPropertyWithDefaultValue`: `int` = `321` - Summary. Description description description description description description description description description. + * `publicPromotedPropertyWithoutDefaultValue`: `int` - Description. + * `publicPropertyEnumWithDefaultValue`: `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum` = `LastDragon_ru\LaraASP\Documentator\Commands\PreprocessTest__Enum::B` - _No description provided_. + * `publicPropertyWithDefaultValue`: `float` = `123.0` - _No description provided_. + * `publicPropertyWithoutDefaultValue`: `int` - Description. MARKDOWN, $command->getProcessedHelpTaskPreprocessParameters( PreprocessTest__Instruction::class,