From c60bf4f9da581cc64bf1f71aa5f8a9eaea28ec52 Mon Sep 17 00:00:00 2001 From: Mathieu Rochette Date: Sun, 22 Sep 2024 19:38:25 +0000 Subject: [PATCH] upgrade docgen --- apigen.neon | 2 +- src/Option.php | 5 +- src/Option/None.php | 64 ++++++++++++--- src/Result/MustBeUsed.php | 5 +- tools/apigen/composer.json | 2 +- .../blocks/classLikeSignatureTable.latte | 35 -------- .../theme/blocks/elementSummaryGroup.latte | 8 +- tools/apigen/theme/blocks/layout.latte | 2 + tools/apigen/theme/blocks/member.latte | 12 --- tools/apigen/theme/blocks/method.latte | 28 +------ tools/apigen/theme/blocks/method2.latte | 79 +++++++++++++++++++ .../apigen/theme/blocks/methodSignature.latte | 18 ----- tools/apigen/theme/classLike.latte | 50 ++++++++++++ tools/apigen/theme/pages/classLike.latte | 2 +- tools/apigen/theme/pages/index.latte | 4 +- tools/apigen/theme/pages/namespace.latte | 3 +- 16 files changed, 208 insertions(+), 111 deletions(-) delete mode 100644 tools/apigen/theme/blocks/classLikeSignatureTable.latte delete mode 100644 tools/apigen/theme/blocks/member.latte create mode 100644 tools/apigen/theme/blocks/method2.latte delete mode 100644 tools/apigen/theme/blocks/methodSignature.latte create mode 100644 tools/apigen/theme/classLike.latte diff --git a/apigen.neon b/apigen.neon index 29d5e14..40f21c7 100644 --- a/apigen.neon +++ b/apigen.neon @@ -2,7 +2,7 @@ parameters: paths: ['%workingDir%/src'] excludeProtected: true excludePrivate: true - excludeTagged: ['internal', 'nodoc'] + excludeTagged: ['@internal', '@nodoc'] outputDir: '%workingDir%/docs' themeDir: tools/apigen/theme title: 'texthtml/maybe' diff --git a/src/Option.php b/src/Option.php index 3b16aa8..2425aeb 100644 --- a/src/Option.php +++ b/src/Option.php @@ -7,8 +7,9 @@ /** * Type `Option` represents an optional value: every `Option` is either - * `Option\Some` and contains a value, or `Option\None`, and does not. `Option` - * types have a number of uses: + * `Option\Some` and contains a value, or `Option\None`, and does not. + * + * `Option` types have a number of uses: * * * Initial values * * Return values for functions that are not defined over their entire input range (partial functions) diff --git a/src/Option/None.php b/src/Option/None.php index 73138c9..81df1ab 100644 --- a/src/Option/None.php +++ b/src/Option/None.php @@ -15,6 +15,8 @@ enum None implements Option case instance; /** + * Returns `false`. + * * @return false */ public function isSome(): bool @@ -23,6 +25,8 @@ public function isSome(): bool } /** + * Returns `true`. + * * @return true */ public function isNone(): bool @@ -31,6 +35,8 @@ public function isNone(): bool } /** + * Returns `false` without calling `$predicate`. + * * @return false */ public function isSomeAnd(callable $predicate): bool @@ -39,6 +45,8 @@ public function isSomeAnd(callable $predicate): bool } /** + * Throws `new \RuntimeException($message)`. + * * @throws \RuntimeException */ public function expect(string $message): never @@ -47,6 +55,8 @@ public function expect(string $message): never } /** + * Throws `new \RuntimeException("Unwrapping a `None` value")`. + * * @throws \RuntimeException */ public function unwrap(): never @@ -54,17 +64,33 @@ public function unwrap(): never $this->expect("Unwrapping a `None` value"); } + /** + * Returns `$default`. + * + * @template U + * @param U $default + * @return U + */ public function unwrapOr(mixed $default): mixed { return $default; } + /** + * Returns `$default()`. + * + * @template U + * @param callable():U $default + * @return U + */ public function unwrapOrElse(callable $default): mixed { return $default(); } /** + * Returns `None` without calling `$callback`. + * * @return $this */ public function inspect(callable $callback): self @@ -73,6 +99,8 @@ public function inspect(callable $callback): self } /** + * Returns `None`. + * * @return $this */ public function and(Option $right): Option @@ -81,6 +109,8 @@ public function and(Option $right): Option } /** + * Returns `None` without calling `$right`. + * * @return $this */ public function andThen(callable $right): Option @@ -88,30 +118,42 @@ public function andThen(callable $right): Option return $this; } + /** + * Returns `$right`. + */ public function or(Option $right): Option { return $right; } + /** + * Returns `$right()`. + */ public function orElse(callable $right): Option { return $right(); } + /** + * Returns `$right`. + */ public function xor(Option $right): Option { return $right; } /** + * Returns `false`. + * * @return false */ public function contains(mixed $value, bool $strict = true): bool { return false; } - /** + * Returns `None` without calling `$predicate`. + * * @return $this */ public function filter(callable $predicate): Option @@ -120,6 +162,8 @@ public function filter(callable $predicate): Option } /** + * Returns `None`. + * * @return $this */ public function map(callable $callback): Option @@ -127,19 +171,25 @@ public function map(callable $callback): Option return $this; } + /** + * Returns `$default` without calling `$callback`. + */ public function mapOr(callable $callback, mixed $default): mixed { return $default; } + /** + * Returns `$default()` without calling `$callback`. + */ public function mapOrElse(callable $callback, callable $default): mixed { return $default(); } /** - * @template U - * @param Option $option + * Returns `None`. + * * @return $this */ public function zip(Option $option): self @@ -148,9 +198,7 @@ public function zip(Option $option): self } /** - * @template E - * @param E $err - * @return Result\Err + * Returns `Result\err($err)`. */ public function okOr(mixed $err): Result\Err { @@ -158,9 +206,7 @@ public function okOr(mixed $err): Result\Err } /** - * @template E - * @param callable():E $err - * @return Result\Err + * Returns `Result\err($err())`. */ public function okOrElse(callable $err): Result\Err { diff --git a/src/Result/MustBeUsed.php b/src/Result/MustBeUsed.php index 27ddefb..74873d8 100644 --- a/src/Result/MustBeUsed.php +++ b/src/Result/MustBeUsed.php @@ -4,7 +4,10 @@ use TH\Maybe\Result; -/** @internal */ +/** + * @internal + * @nodoc + */ trait MustBeUsed { /** @var \ArrayAccess,ResultCreationTrace>|null */ diff --git a/tools/apigen/composer.json b/tools/apigen/composer.json index 92c165b..770bfef 100644 --- a/tools/apigen/composer.json +++ b/tools/apigen/composer.json @@ -5,7 +5,7 @@ } }, "require": { - "apigen/apigen": "^7.0@alpha" + "apigen/apigen": "dev-master" }, "require-dev": { "tracy/tracy": "^2.9" diff --git a/tools/apigen/theme/blocks/classLikeSignatureTable.latte b/tools/apigen/theme/blocks/classLikeSignatureTable.latte deleted file mode 100644 index baea8e7..0000000 --- a/tools/apigen/theme/blocks/classLikeSignatureTable.latte +++ /dev/null @@ -1,35 +0,0 @@ -{varType ApiGen\Index\Index $index} -{varType ApiGen\Renderer\Latte\Template\ConfigParameters $config} -{varType ApiGen\Renderer\Latte\Template\LayoutParameters $layout} - -{define classLikeSignatureTable, ApiGen\Info\ClassLikeInfo $classLike} - - {if isClass($classLike)} - {if $classLike->abstract}{/if} - {if $classLike->final}{/if} - {include classLikeSignatureTableRow, 'extends', $classLike->extends ? [$classLike->extends] : []} - {include classLikeSignatureTableRow, 'implements', $classLike->implements} - - {elseif isInterface($classLike)} - {include classLikeSignatureTableRow, 'extends', $classLike->extends} - - {elseif isEnum($classLike)} - {include classLikeSignatureTableRow, 'implements', $classLike->implements} - {/if} -
abstract
final
-{/define} - -{define classLikeSignatureTableRow, string $label, ApiGen\Info\ClassLikeReferenceInfo[] $refs} - {if $refs} - - {$label} - - - {foreach $refs as $ref} - {include classLikeReference, $ref}{sep}, {/sep} - {/foreach} - - - - {/if} -{/define} diff --git a/tools/apigen/theme/blocks/elementSummaryGroup.latte b/tools/apigen/theme/blocks/elementSummaryGroup.latte index 4c64d15..7b434c5 100644 --- a/tools/apigen/theme/blocks/elementSummaryGroup.latte +++ b/tools/apigen/theme/blocks/elementSummaryGroup.latte @@ -2,16 +2,20 @@ {varType ApiGen\Renderer\Latte\Template\ConfigParameters $config} {varType ApiGen\Renderer\Latte\Template\LayoutParameters $layout} -{define elementSummaryGroup, ApiGen\Info\ElementInfo[] $elements, bool $showDescription = true, bool $onlyPrimary = false} +{define elementSummaryGroup, string $heading, ApiGen\Info\ElementInfo[] $elements, bool $showDescription = true, bool $onlyPrimary = false} {try} +

{$heading}

+ {foreach $elements as $element} {skipIf $onlyPrimary && !$element->primary} + {skipIf !elementPageExists($element)}

{elementName($element)}

- {if $showDescription}{longDescription($element->description)}{/if} + {if $showDescription}{elementShortDescription($index, null, $element)}{/if}

{else} {rollback} {/foreach} + {/try} {/define} diff --git a/tools/apigen/theme/blocks/layout.latte b/tools/apigen/theme/blocks/layout.latte index d97b172..5ca4016 100644 --- a/tools/apigen/theme/blocks/layout.latte +++ b/tools/apigen/theme/blocks/layout.latte @@ -8,6 +8,7 @@ + {if $layout->noindex}{/if} {ifset title}{include title|spaceless} | {/ifset}{$config->title} API @@ -18,6 +19,7 @@ } + {include head} diff --git a/tools/apigen/theme/blocks/member.latte b/tools/apigen/theme/blocks/member.latte deleted file mode 100644 index f698c11..0000000 --- a/tools/apigen/theme/blocks/member.latte +++ /dev/null @@ -1,12 +0,0 @@ -{varType ApiGen\Index\Index $index} -{varType ApiGen\Renderer\Latte\Template\ConfigParameters $config} -{varType ApiGen\Renderer\Latte\Template\LayoutParameters $layout} - -{define member, ApiGen\Info\MemberInfo $member} - - {include cells} - - # - - -{/define} diff --git a/tools/apigen/theme/blocks/method.latte b/tools/apigen/theme/blocks/method.latte index ff3c6e4..36a8a3a 100644 --- a/tools/apigen/theme/blocks/method.latte +++ b/tools/apigen/theme/blocks/method.latte @@ -18,42 +18,20 @@
{foreach $method->tags['deprecated'] ?? [] as $tag} {skipIf !$tag->description} - {longDescription($tag->description)}{sep}
{/sep} + {longDescription($index, $classLike, $tag->description)}{sep}
{/sep} {else} {rollback} {/foreach}
{/try} - {try} -

Parameters

- - {foreach $method->parameters as $parameter} - {var string $description = $parameter->getEffectiveDescription($index, $classLike, $method)} - {skipIf $description === ''} - - - - - {else} - {rollback} - {/foreach} -
{if $parameter->variadic}...{/if}${$parameter->name}  {longDescription($description)}
- {/try} - - {var string $returnDescription = $method->getEffectiveReturnDescription($index, $classLike)} - {if $returnDescription !== ''} -

Returns

-
{longDescription($returnDescription)}
- {/if} - {if !empty($method->tags['throws'])}

Throws

{foreach $method->tags['throws'] as $tag} - - + + {/foreach}
{include type, type: $tag->type, short: false} {longDescription($tag->description)}{include type, type: $tag->type, scope: $classLike, short: false} {longDescription($index, $classLike, $tag->description)}
diff --git a/tools/apigen/theme/blocks/method2.latte b/tools/apigen/theme/blocks/method2.latte new file mode 100644 index 0000000..18dc3e1 --- /dev/null +++ b/tools/apigen/theme/blocks/method2.latte @@ -0,0 +1,79 @@ +{varType ApiGen\Index\Index $index} +{varType ApiGen\Renderer\Latte\Template\ConfigParameters $config} +{varType ApiGen\Renderer\Latte\Template\LayoutParameters $layout} + +{define method, ApiGen\Info\ClassLikeInfo $classLike, ApiGen\Info\MethodInfo $method} + {embed member, $method} + {block cells} + + + {if !isInterface($classLike) && $method->abstract}abstract{elseif $method->final}final{/if} + {include memberVisibility, $method} + {if $method->static}static{/if} + {if $method->byRef}&{/if} + + + + + {include methodSignature, classLike: $classLike, method: $method} + + {embed memberDescription, classLike: $classLike, member: $method} + {block details} + {try} +

Deprecated

+
+ {foreach $method->tags['deprecated'] ?? [] as $tag} + {skipIf !$tag->description} + {longDescription($tag->description)}{sep}
{/sep} + {else} + {rollback} + {/foreach} +
+ {/try} + + {try} +

Parameters

+ + {foreach $method->parameters as $parameter} + {var string $description = $parameter->getEffectiveDescription($index, $classLike, $method)} + {skipIf $description === ''} + + + + + {else} + {rollback} + {/foreach} +
{if $parameter->variadic}...{/if}${$parameter->name}  {longDescription($description)}
+ {/try} + + {var string $returnDescription = $method->getEffectiveReturnDescription($index, $classLike)} + {if $returnDescription !== ''} +

Returns

+
{longDescription($returnDescription)}
+ {/if} + + {if !empty($method->tags['throws'])} +

Throws

+ + {foreach $method->tags['throws'] as $tag} + + + + + {/foreach} +
{include type, type: $tag->type, short: false} {longDescription($tag->description)}
+ {/if} + + {* TODO: other tags (uses, internal...) *} + + {include methodRelation, title: 'Overrides', method: $method, related: $index->methodOverrides[$classLike->name->fullLower][$method->nameLower] ?? []} + {include methodRelation, title: 'Overriden by', method: $method, related: $index->methodOverriddenBy[$classLike->name->fullLower][$method->nameLower] ?? []} + {include methodRelation, title: 'Implements', method: $method, related: $index->methodImplements[$classLike->name->fullLower][$method->nameLower] ?? []} + {include methodRelation, title: 'Implemented by', method: $method, related: $index->methodImplementedBy[$classLike->name->fullLower][$method->nameLower] ?? []} + {/block} + {/embed} + + {/block} + {/embed} +{/define} diff --git a/tools/apigen/theme/blocks/methodSignature.latte b/tools/apigen/theme/blocks/methodSignature.latte deleted file mode 100644 index 0d13d55..0000000 --- a/tools/apigen/theme/blocks/methodSignature.latte +++ /dev/null @@ -1,18 +0,0 @@ -{varType ApiGen\Index\Index $index} -{varType ApiGen\Renderer\Latte\Template\ConfigParameters $config} -{varType ApiGen\Renderer\Latte\Template\LayoutParameters $layout} - -{define methodSignature, ApiGen\Info\ClassLikeInfo $classLike, ApiGen\Info\MethodInfo $method} - {pre} - {embed autoBreakingLine, items: $method->parameters, maxWidth: 120} - {block before} - {$method->name} - {include genericParameters, $method->genericParameters} - ( - {/block} - {block after}){if $method->returnType}: {include type, type: $method->returnType}{/if}{/block} - {block item}{include parameter, classLike: $classLike, parameter: $item}{/block} - {block sep},{/block} - {/embed} - {/pre} -{/define} diff --git a/tools/apigen/theme/classLike.latte b/tools/apigen/theme/classLike.latte new file mode 100644 index 0000000..f2524a3 --- /dev/null +++ b/tools/apigen/theme/classLike.latte @@ -0,0 +1,50 @@ +{templateType ApiGen\Renderer\Latte\Template\ClassLikeTemplate} +{import '../blocks/@index.latte'} + +{embed layout} + {block title} + {if $classLike->isDeprecated()}Deprecated {/if} + {include classLikeKind, $classLike} + {$classLike->name->full} + {/block} + + {block content} +

+ {include classLikeKind, $classLike} {include classLikeLinks, $classLike} +

+ + {if $classLike->genericParameters} +

{include genericParameters, $classLike->genericParameters}

+ {/if} + + {include classLikeSignatureTable, $classLike} + {include classLikeDescription, $classLike} + + {if !empty($index->dag[$classLike->name->fullLower]) || (isClass($classLike) && $classLike->extends) || (isInterface($classLike) && $classLike->extends)} +
+ {include classTree, $classLike, $index->dag} +
+ {/if} + +
+ {if $classLike->file && sourcePageExists($index->files[$classLike->file])}Located at {relativePath($classLike->file)}
{/if} +
+ + {include aliasSummary, $classLike} + + {if isEnum($classLike)} + {include enumCaseSummary, $classLike} + {/if} + + {include methodSummary, $classLike} + {include methodInheritedSummary, $classLike, []} + {include methodUsedSummary, $classLike, []} + + {include constantSummary, $classLike} + {include constantInheritedSummary, $classLike, []} + + {include propertySummary, $classLike} + {include propertyInheritedSummary, $classLike, []} + {include propertyUsedSummary, $classLike, []} + {/block} +{/embed} diff --git a/tools/apigen/theme/pages/classLike.latte b/tools/apigen/theme/pages/classLike.latte index f5bdfad..f887c43 100644 --- a/tools/apigen/theme/pages/classLike.latte +++ b/tools/apigen/theme/pages/classLike.latte @@ -16,9 +16,9 @@ {/if} - {include classLikeSignatureTable, $classLike} {include classLikeDescription, $classLike} + {include aliasSummary, $classLike} {if isEnum($classLike)} {include enumCaseSummary, $classLike} diff --git a/tools/apigen/theme/pages/index.latte b/tools/apigen/theme/pages/index.latte index d7c6887..3f9d8b3 100644 --- a/tools/apigen/theme/pages/index.latte +++ b/tools/apigen/theme/pages/index.latte @@ -3,14 +3,14 @@ {embed layout} {block content} -

TH\Maybe

+

Overview

This library implements two monadic types for PHP :

Option
Type Option represents an optional value: every Option is either - Option\Some and contains a value, or Option\None, and does not + Option\Some and contains a value, or Option\None, and does not.
Result
diff --git a/tools/apigen/theme/pages/namespace.latte b/tools/apigen/theme/pages/namespace.latte index 376f488..00d7d8a 100644 --- a/tools/apigen/theme/pages/namespace.latte +++ b/tools/apigen/theme/pages/namespace.latte @@ -10,12 +10,11 @@ {embed elementSummary} {block elementSummaryContent} {include elementSummaryGroup, heading: 'Classes', elements: $namespace->class, onlyPrimary: $namespace->primary} - {include elementSummaryGroup, heading: 'Interfaces', elements: $namespace->interface, onlyPrimary: $namespace->primary} + {include elementSummaryGroup, elements: $namespace->interface, onlyPrimary: $namespace->primary} {include elementSummaryGroup, heading: 'Traits', elements: $namespace->trait, onlyPrimary: $namespace->primary} {include elementSummaryGroup, heading: 'Enums', elements: $namespace->enum, onlyPrimary: $namespace->primary} {include elementSummaryGroup, heading: 'Exceptions', elements: $namespace->exception, onlyPrimary: $namespace->primary} {include elementSummaryGroup, heading: 'Functions', elements: $namespace->function, onlyPrimary: $namespace->primary} - {include elementSummaryGroup, heading: 'Namespaces', elements: $namespace->children, showDescription: false, onlyPrimary: $namespace->primary} {/block} {/embed} {/block}