Add external error handling support and rename "add" method "register"

Author: Kirill Nesmeyanov

src/Factory.php

@@ -4,6 +4,9 @@
 
 namespace TypeLang\PHPDoc;
 
+use TypeLang\PHPDoc\Exception\InvalidTagException;
+use TypeLang\PHPDoc\Exception\ParsingException;
+use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 use TypeLang\PHPDoc\Tag\Tag;
 
@@ -16,7 +19,7 @@ public function __construct(
         private array $factories = [],
     ) {}
 
-    public function add(array|string $tags, FactoryInterface $delegate): void
+    public function register(array|string $tags, FactoryInterface $delegate): void
     {
         foreach ((array) $tags as $tag) {
             $this->factories[$tag] = $delegate;
@@ -28,7 +31,24 @@ public function create(string $name, string $content, DescriptionParserInterface
         $delegate = $this->factories[$name] ?? null;
 
         if ($delegate !== null) {
-            return $delegate->create($name, $content, $descriptions);
+            try {
+                return $delegate->create($name, $content, $descriptions);
+            } catch (ParsingException $e) {
+                throw $e;
+            } catch (RuntimeExceptionInterface $e) {
+                throw InvalidTagException::fromCreatingTag(
+                    tag: $name,
+                    source: $e->getSource(),
+                    offset: $e->getOffset(),
+                    prev: $e,
+                );
+            } catch (\Throwable $e) {
+                throw InvalidTagException::fromCreatingTag(
+                    tag: $name,
+                    source: $content,
+                    prev: $e,
+                );
+            }
         }
 
         return new Tag($name, $descriptions->parse($content));

src/FactoryInterface.php

@@ -4,6 +4,7 @@
 
 namespace TypeLang\PHPDoc;
 
+use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 use TypeLang\PHPDoc\Tag\Tag;
 
@@ -13,6 +14,9 @@ interface FactoryInterface
      * Returns a tag object with the specified name and description.
      *
      * @param non-empty-string $name
+     *
+     * @throws RuntimeExceptionInterface In case of parsing error occurs.
+     * @throws \Throwable In case of internal error occurs.
      */
     public function create(string $name, string $content, DescriptionParserInterface $descriptions): Tag;
 }

src/MutableFactoryInterface.php

@@ -9,5 +9,5 @@ interface MutableFactoryInterface extends FactoryInterface
     /**
      * @param non-empty-string|list<non-empty-string> $tags
      */
-    public function add(string|array $tags, FactoryInterface $delegate): void;
+    public function register(string|array $tags, FactoryInterface $delegate): void;
 }