Improve some tag formatting

Author: SerafimArts

docs/Writerside/topics/phpdoc/tags/category-tag.md

@@ -24,8 +24,8 @@ module, `@category` places that module within a wider organizational scheme.
 > With additional context about the grouping.
 > ```php
 > /**
->  * @category Database Drivers and connection pooling for
->  *           relational stores.
+>  * @category Database Drivers and connection pooling for relational
+>  *           stores.
 >  */
 > ```
 

docs/Writerside/topics/phpdoc/tags/example-tag.md

@@ -26,8 +26,8 @@ reused across several tags that each highlight a different part of it.
 > Narrowed to the lines that show the relevant usage.
 > ```php
 > /**
->  * @example docs/examples/mailer-retry.php 12 8 Configuring a
->  *          retry policy.
+>  * @example docs/examples/mailer-retry.php 12 8 Configuring a retry
+>  *          policy.
 >  */
 > public function withRetries(int $attempts): static
 > ```

docs/Writerside/topics/phpdoc/tags/link-tag.md

@@ -25,8 +25,8 @@ be a well-formed URI, never a class, method, or constant reference.
 > relevant.
 > ```php
 > /**
->  * @link https://example.com/docs/rate-limits
->  * Applies to all public endpoints.
+>  * @link https://example.com/docs/rate-limits Applies to all public
+>  *       endpoints.
 >  */
 > ```
 

docs/Writerside/topics/phpdoc/tags/no-named-arguments-tag.md

@@ -27,8 +27,8 @@ stays free to rename parameters without it counting as a break.
 > With a description explaining why.
 > ```php
 > /**
->  * @no-named-arguments Parameter names will
->  * change once the driver abstraction lands.
+>  * @no-named-arguments Parameter names will change once the driver
+>  *                     abstraction lands.
 >  */
 > function connect(string $dsn, ?string $user, ?string $password): PDO
 > ```

docs/Writerside/topics/phpdoc/tags/override-tag.md

@@ -25,8 +25,7 @@ attribute has no effect.
 > implementation.
 > ```php
 > /**
->  * @override Adds retry handling on top of the
->  *           base transport.
+>  * @override Adds retry handling on top of the base transport.
 >  */
 > public function send(Message $message): bool
 > ```

docs/Writerside/topics/phpdoc/tags/param-closure-this-tag.md

@@ -28,9 +28,9 @@ closure that reads `$this` has no documented type to check against.
 > ```php
 > /**
 >  * @param Closure(int): void $callback
->  * @param-closure-this Connection $callback
->  * Bound before dispatch so the callback can
->  * reach the connection's protected members.
+>  * @param-closure-this Connection $callback Bound before dispatch so
+>  *                     the callback can reach the connection's
+>  *                     protected members.
 >  */
 > function onConnect(Closure $callback): void
 > ```

docs/Writerside/topics/phpdoc/tags/param-immediately-invoked-callable-tag.md

@@ -29,9 +29,10 @@ callable might be kept and invoked at some unrelated point in time.
 > With a description explaining why it matters here.
 > ```php
 > /**
->  * @param-immediately-invoked-callable $callback
->  * Runs before the lock is released, so it can
->  * safely mutate the shared buffer.
+>  * @param-immediately-invoked-callable $callback Runs before the
+>  *                                     lock is released, so it can
+>  *                                     safely mutate the shared
+>  *                                     buffer.
 >  */
 > function withLock(callable $callback): mixed
 > ```

docs/Writerside/topics/phpdoc/tags/param-later-invoked-callable-tag.md

@@ -31,9 +31,9 @@ be assumed pure just because the callback itself might be.
 > With a description explaining when it actually runs.
 > ```php
 > /**
->  * @param-later-invoked-callable $callback
->  * Invoked once the response arrives, which
->  * may be long after this method returns.
+>  * @param-later-invoked-callable $callback Invoked once the response
+>  *                               arrives, which may be long after
+>  *                               this method returns.
 >  */
 > function then(callable $callback): static
 > ```

docs/Writerside/topics/phpdoc/tags/param-out-tag.md

@@ -31,7 +31,7 @@ analyzers are stuck assuming the same type applies in both directions.
 > /**
 >  * @param list<int> $matches
 >  * @param-out non-empty-list<int> $matches Populated only when the
->  * function returns true.
+>  *            function returns true.
 >  */
 > function findAll(string $pattern, array &$matches): bool
 > ```

docs/Writerside/topics/phpdoc/tags/property-read-tag.md

@@ -28,7 +28,7 @@ accidental assignment to a value that the class was never meant to accept.
 > ```php
 > /**
 >  * @property-read DateTimeImmutable $createdAt When the record was
->  *     inserted.
+>  *                inserted.
 >  */
 > class Record {}
 > ```