Skip to content

Commit

Permalink
feat(documentator): Deprecation mark output in generated help of `lar…
Browse files Browse the repository at this point in the history 
…a-asp-documentator:preprocess` command.
  • Loading branch information
@LastDragon-ru
LastDragon-ru committed Nov 29, 2024
1 parent fc1048b commit cd2ac7d
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 26 deletions.
16 changes: 8 additions & 8 deletions packages/documentator/docs/Commands/preprocess.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ run with default/normal level if it is not specified in its arguments.

* `<target>` - File path.
* `<parameters>` - 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 `<target>` file. Inline tags include as is except `@see`/`@link`
Expand All @@ -72,16 +72,16 @@ which will be replaced to FQCN (if possible). Other tags are ignored.
* `<parameters>` - 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`: `<current level> + 1`
* `int`: explicit level (`1-6`)
* `0`: `<current level>`
* `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 `<target>` directory. Each file
must have `# Header` as the first construction. The first paragraph
Expand Down Expand Up @@ -120,12 +120,12 @@ Includes the `<target>` file.

Includes the definition of the directive as a Markdown code block.

#### `[include:package-list]: <target> <parameters>`
#### `[include:package-list]: <target> <parameters>` 💀

* `<target>` - Directory path.
* `<parameters>` - 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 `<target>` directory. The readme file will be
used to determine package name and summary.
Expand Down
41 changes: 31 additions & 10 deletions packages/documentator/src/Commands/Preprocess.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 .= <<<MARKDOWN
{$heading} {$title} ({$extensions})
{$heading} {$title} ({$extensions}){$deprecated}
{$description}
Expand Down Expand Up @@ -171,17 +174,20 @@ protected function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $ta
$help = [];

foreach ($instructions as $instruction) {
$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);
$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(
<<<HELP
{$heading} `[{$name}]: <target> <parameters>`
{$heading} `[{$name}]: <target> <parameters>`{$deprecated}
* `<target>` - {$target}
* `<parameters>` - additional parameters
Expand All @@ -193,7 +199,7 @@ protected function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $ta
} else {
$help[$name] = rtrim(
<<<HELP
{$heading} `[{$name}]: <target>`
{$heading} `[{$name}]: <target>`{$deprecated}
* `<target>` - {$target}
Expand Down Expand Up @@ -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;
Expand All @@ -298,6 +305,9 @@ protected function getProcessedHelpTaskPreprocessParameters(
return null;
}

// Sort
ksort($parameters);

// Serialize
$list = '';

Expand Down Expand Up @@ -346,4 +356,15 @@ private function getDocBlock(
// Return
return trim($help);
}

/**
* @param ReflectionClass<object>|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;
}
}
16 changes: 8 additions & 8 deletions packages/documentator/src/Commands/PreprocessTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
* `<parameters>` - 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.
Expand Down Expand Up @@ -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,
Expand Down

0 comments on commit cd2ac7d

Please sign in to comment.