upgrade docgen

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'

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)

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,24 +55,42 @@ public function expect(string $message): never
     }
 
     /**
+     * Throws `new \RuntimeException("Unwrapping a `None` value")`.
+     *
      * @throws \RuntimeException
      */
     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,37 +109,51 @@ public function and(Option $right): Option
     }
 
     /**
+     * Returns `None` without calling `$right`.
+     *
      * @return $this
      */
     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,26 +162,34 @@ public function filter(callable $predicate): Option
     }
 
     /**
+     * Returns `None`.
+     *
      * @return $this
      */
     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<U> $option
+     * Returns `None`.
+     *
      * @return $this
      */
     public function zip(Option $option): self
@@ -148,19 +198,15 @@ public function zip(Option $option): self
     }
 
     /**
-     * @template E
-     * @param E $err
-     * @return Result\Err<E>
+     * Returns `Result\err($err)`.
      */
     public function okOr(mixed $err): Result\Err
     {
         return Result\err($err);
     }
 
     /**
-     * @template E
-     * @param callable():E $err
-     * @return Result\Err<E>
+     * Returns `Result\err($err())`.
      */
     public function okOrElse(callable $err): Result\Err
     {

src/Result/MustBeUsed.php

@@ -4,7 +4,10 @@
 
 use TH\Maybe\Result;
 
-/** @internal */
+/**
+ * @internal
+ * @nodoc
+ */
 trait MustBeUsed
 {
     /** @var \ArrayAccess<Result<mixed,mixed>,ResultCreationTrace>|null */

tools/apigen/composer.json

@@ -5,7 +5,7 @@
         }
     },
     "require": {
-        "apigen/apigen": "^7.0@alpha"
+        "apigen/apigen": "dev-master"
     },
     "require-dev": {
         "tracy/tracy": "^2.9"

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}
+		<h2>{$heading}</h2>
+
 		{foreach $elements as $element}
 			{skipIf $onlyPrimary && !$element->primary}
+			{skipIf !elementPageExists($element)}
 			<p>
 				<h3><a href="{elementUrl($element)}" n:class="$element->isDeprecated() ? deprecated">{elementName($element)}</a></h3>
-				{if $showDescription}{longDescription($element->description)}{/if}
+				{if $showDescription}{elementShortDescription($index, null, $element)}{/if}
 			</p>
 		{else}
 			{rollback}
 		{/foreach}
+
 	{/try}
 {/define}

tools/apigen/theme/blocks/layout.latte

@@ -8,6 +8,7 @@
 <head>
 	<meta charset="utf-8">
 	<meta name="viewport" content="width=device-width">
+	{if $layout->noindex}<meta name="robots" content="noindex">{/if}
 	<title>{ifset title}{include title|spaceless} | {/ifset}{$config->title} API</title>
 	<link rel="stylesheet" href="{assetUrl('main.css')}">
 	<link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/themes/prism.css" rel="stylesheet" />
@@ -18,6 +19,7 @@
 		}
 	</style>
 	<script src="{assetUrl('main.js')}" defer></script>
+	{include head}
 </head>
 
 <body class="layout">

tools/apigen/theme/blocks/method.latte

@@ -18,42 +18,20 @@
 				<div>
 					{foreach $method->tags['deprecated'] ?? [] as $tag}
 						{skipIf !$tag->description}
-						{longDescription($tag->description)}{sep}<br>{/sep}
+						{longDescription($index, $classLike, $tag->description)}{sep}<br>{/sep}
 					{else}
 						{rollback}
 					{/foreach}
 				</div>
 			{/try}
 
-			{try}
-				<h4>Parameters</h4>
-				<table>
-					{foreach $method->parameters as $parameter}
-						{var string $description = $parameter->getEffectiveDescription($index, $classLike, $method)}
-						{skipIf $description === ''}
-						<tr>
-							<td>{if $parameter->variadic}...{/if}<var>${$parameter->name}</var>&nbsp;&nbsp;</td>
-							<td>{longDescription($description)}</td>
-						</tr>
-					{else}
-						{rollback}
-					{/foreach}
-				</table>
-			{/try}
-
-			{var string $returnDescription = $method->getEffectiveReturnDescription($index, $classLike)}
-			{if $returnDescription !== ''}
-				<h4>Returns</h4>
-				<div>{longDescription($returnDescription)}</div>
-			{/if}
-
 			{if !empty($method->tags['throws'])}
 				<h4>Throws</h4>
 				<table>
 					{foreach $method->tags['throws'] as $tag}
 						<tr>
-							<td><code>{include type, type: $tag->type, short: false}</code>&nbsp;</td>
-							<td>{longDescription($tag->description)}</td>
+							<td><code>{include type, type: $tag->type, scope: $classLike, short: false}</code>&nbsp;</td>
+							<td>{longDescription($index, $classLike, $tag->description)}</td>
 						</tr>
 					{/foreach}
 				</table>