Add "@Final" tag support

Author: Kirill Nesmeyanov

README.md

@@ -32,7 +32,7 @@ composer require type-lang/phpdoc
 
 ## Supported Tags
 
-- [x] `@abstract` - Declare a class-like _Symbol_ or method as abstract
+- [x] `@abstract` - Declare any _Symbol_ as abstract
 - [ ] `@api` - TODO
 - [ ] `@author` - TODO
 - [ ] `@category` - TODO
@@ -41,7 +41,7 @@ composer require type-lang/phpdoc
 - [ ] `@example` - TODO
 - [x] `@extends` - Allows to extend templated classes and interfaces
 - [ ] `@filesource` - TODO
-- [ ] `@final` - TODO
+- [x] `@final` - Declare any _Symbol_ as final
 - [ ] `@global` - TODO
 - [ ] `@ignore` - TODO
 - [x] `@implements` - Allows to extend templated interfaces

src/DocBlock/Tag/FinalTag/FinalTag.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\FinalTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Tag;
+
+/**
+ * Used to denote that the associated _Symbol_ is final, are not allowed to
+ * extend or override the _Symbol_ in a child element.
+ *
+ * In some situations the language construct final cannot be used by the
+ * implementing library where the functionality of the library prevents
+ * elements from being final. For example when proxy patterns are applied.
+ * In these cases the "`@final`" tag can be used to indicate that the element
+ * should be treated as final.
+ *
+ * The optional description is used to provide a more detailed explanation of
+ * why the element is marked as final.
+ *
+ * IDE's and other tools can use this information to show an error when such
+ * an element is extended or overridden.
+ *
+ * ```
+ * "@final" [<description>]
+ * ```
+ */
+final class FinalTag extends Tag
+{
+    public function __construct(
+        string $name,
+        \Stringable|string|null $description = null,
+    ) {
+        parent::__construct($name, $description);
+    }
+}

src/DocBlock/Tag/FinalTag/FinalTagFactory.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\FinalTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+use TypeLang\PHPDoc\Parser\Content\Stream;
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+
+/**
+ * This class is responsible for creating "`@final`" tags.
+ *
+ * See {@see FinalTag} for details about this tag.
+ */
+final class FinalTagFactory implements TagFactoryInterface
+{
+    public function create(string $tag, string $content, DescriptionParserInterface $descriptions): FinalTag
+    {
+        $stream = new Stream($tag, $content);
+
+        return new FinalTag(
+            name: $tag,
+            description: $stream->toOptionalDescription($descriptions),
+        );
+    }
+}

src/Platform/StandardPlatform.php

@@ -7,6 +7,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\AbstractTag\AbstractTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\FinalTag\FinalTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\LinkTag\LinkTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\MethodTag\MethodTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\ParamTag\ParamTagFactory;
@@ -34,6 +35,7 @@ protected function load(TypesParserInterface $types): iterable
     {
         yield 'abstract' => new AbstractTagFactory();
         yield 'extends' => new TemplateExtendsTagFactory($types);
+        yield 'final' => new FinalTagFactory();
         yield 'implements' => new TemplateImplementsTagFactory($types);
         yield 'link' => new LinkTagFactory();
         yield 'method' => new MethodTagFactory($types);