Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better include:document-list instruction #204

Merged
merged 3 commits into from
Nov 29, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
feat(documentator): Deprecation mark output in generated help of `lar…
…a-asp-documentator:preprocess` command.
LastDragon-ru committed Nov 29, 2024

Verified

This commit was signed with the committer’s verified signature. The key has expired.
LastDragon-ru Aleksei Lebedev
commit cd2ac7d57f4170abb4d7e52b4a183727d3e9ea6b
16 changes: 8 additions & 8 deletions packages/documentator/docs/Commands/preprocess.md
Original file line number Diff line number Diff line change
@@ -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`
@@ -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
@@ -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.
41 changes: 31 additions & 10 deletions packages/documentator/src/Commands/Preprocess.php
Original file line number Diff line number Diff line change
@@ -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 .= <<<MARKDOWN
{$heading} {$title} ({$extensions})
{$heading} {$title} ({$extensions}){$deprecated}

{$description}

@@ -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
@@ -193,7 +199,7 @@ protected function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $ta
} else {
$help[$name] = rtrim(
<<<HELP
{$heading} `[{$name}]: <target>`
{$heading} `[{$name}]: <target>`{$deprecated}

* `<target>` - {$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<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
Original file line number Diff line number Diff line change
@@ -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.

@@ -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,