Improve tag formatting and fix some typos

Author: SerafimArts

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

@@ -20,16 +20,13 @@ documentation.
 >  * @method void handle(Event $event)
 >  * @abstract
 >  */
-> abstract class Listener
-> {
-> }
+> abstract class Listener {}
 > ```
 
 > With a description explaining what implementers must provide.
 > ```php
 > /**
->  * @abstract Subclasses must return the
->  *           storage backend to use.
+>  * @abstract Subclasses must return the storage backend to use.
 >  */
 > protected function makeStorage(): Storage
 > ```

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

@@ -22,16 +22,13 @@ appears in generated documentation.
 >  * @property string $token
 >  * @access private
 >  */
-> class Session
-> {
-> }
+> class Session {}
 > ```
 
 > With a description explaining the reasoning.
 > ```php
 > /**
->  * @access protected Only subclasses should
->  *         read the raw buffer.
+>  * @access protected Only subclasses should read the raw buffer.
 >  */
 > ```
 

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

@@ -17,20 +17,15 @@ releases without a deprecation notice.
 > /**
 >  * @api
 >  */
-> final class Mailer
-> {
-> }
+> final class Mailer {}
 > ```
 
 > With a description explaining the guarantee.
 > ```php
 > /**
->  * @api Stable since 2.0; changes follow
->  *      semantic versioning.
+>  * @api Stable since 2.0; changes follow semantic versioning.
 >  */
-> public function send(
->     Message $message,
-> ): bool
+> public function send(Message $message): bool
 > ```
 
 Parsing an `@api` tag produces an `ApiTag` instance. Being a pure marker, it

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

@@ -36,16 +36,16 @@ Parsing an `@author` tag produces an `AuthorTag` instance exposing:
 final class AuthorTag extends Tag
 {
     public function __construct(
+        string $name,
         public readonly string $author,
         public readonly ?string $email = null,
+        ?DescriptionInterface $description = null,
     ) {
+        parent::__construct($name, $description);
     }
 }
 ```
 
-Every tag also carries `$name` and an optional `$description` inherited
-from the base `Tag` class, omitted above for brevity.
-
 Multiple `@author` tags may appear on the same element when several people
 share responsibility for it; each one is parsed independently.
 

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/coding-standards-tag.md

@@ -19,5 +19,4 @@ suffix folded into the description. See
 need to recognize it yourself.
 </note>
 
-Associated with PHP_CodeSniffer; this exact tag spelling could not be
-confirmed in PHP_CodeSniffer's own documentation.
+Associated with PHP_CodeSniffer.

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

@@ -17,16 +17,13 @@ without having to parse a separate license header.
 > /**
 >  * @copyright 2024 Acme Corp
 >  */
-> final class Mailer
-> {
-> }
+> final class Mailer {}
 > ```
 
 > A range of years, used on a file that has been maintained over time.
 > ```php
 > /**
->  * @copyright 2018-2024 Acme Corp.
->  *            All rights reserved.
+>  * @copyright 2018-2024 Acme Corp. All rights reserved.
 >  */
 > ```
 

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

@@ -16,37 +16,29 @@ deprecated and what to use in its place.
 > /**
 >  * @deprecated 2.0 Use Mailer::send() instead.
 >  */
-> public function dispatch(
->     Message $message,
-> ): bool
+> public function dispatch(Message $message): bool
 > ```
 
 > Without a version, just explaining the reason.
 > ```php
 > /**
->  * @deprecated No longer needed now that
->  *             transport is chosen
+>  * @deprecated No longer needed now that transport is chosen
 >  *             automatically.
 >  */
-> public function withTransport(
->     Transport $transport,
-> ): static
+> public function withTransport(Transport $transport): static
 > ```
 
 Parsing a `@deprecated` tag produces a `DeprecatedTag` instance exposing
 `$version` — the version since which the element is deprecated, or `null`
 when none was given — alongside the inherited `$description`.
 
 ```php
-final class DeprecatedTag extends VersionedTag
-{
-    public function __construct(
-        public readonly ?string $version = null,
-    ) {
-    }
-}
+final class DeprecatedTag extends VersionedTag {}
 ```
 
+`VersionedTag` itself declares the `$version` property (and the
+constructor that fills it in) — `DeprecatedTag` adds nothing of its own.
+
 <note>
 IDEs and static analyzers commonly treat <code>@deprecated</code> as more
 than documentation: every call site of the annotated element is typically

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

@@ -20,20 +20,16 @@ reused across several tags that each highlight a different part of it.
 > /**
 >  * @example docs/examples/mailer-basic.php
 >  */
-> public function send(
->     Message $message,
-> ): bool
+> public function send(Message $message): bool
 > ```
 
 > 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
+> public function withRetries(int $attempts): static
 > ```
 
 Parsing an `@example` tag produces an `ExampleTag` instance exposing:

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

@@ -18,9 +18,7 @@ hierarchy.
 > /**
 >  * @extends Collection<User>
 >  */
-> final class UserCollection extends Collection
-> {
-> }
+> final class UserCollection extends Collection {}
 > ```
 
 > Forwarding a still-open type parameter to a further subclass.
@@ -29,9 +27,7 @@ hierarchy.
 >  * @template T
 >  * @extends Repository<T>
 >  */
-> abstract class BaseRepository extends Repository
-> {
-> }
+> abstract class BaseRepository extends Repository {}
 > ```
 
 Parsing an `@extends` tag produces a tag exposing `$type` — the parsed