Add exception TODOs

Author: SerafimArts

libs/phpdoc/src/DocBlock/Tag/TagFactory.php

@@ -10,8 +10,6 @@
 {
     public function create(string $name, string $suffix, DescriptionParserInterface $descriptions): TagInterface
     {
-        // throw new \LogicException('asd');
-
         return new Tag($name, $descriptions->tryParse($suffix));
     }
 }

libs/phpdoc/src/DocBlockParser.php

@@ -13,7 +13,6 @@
 use TypeLang\PhpDoc\Exception\ParsingExceptionInterface;
 use TypeLang\PhpDoc\Parser\Description\BalancedBraceAwareParser;
 use TypeLang\PhpDoc\Parser\Description\DescriptionParserInterface;
-use TypeLang\PhpDoc\Parser\SourceMap;
 use TypeLang\PhpDoc\Parser\Splitter\SplitterInterface;
 use TypeLang\PhpDoc\Parser\Splitter\StringSplitter;
 use TypeLang\PhpDoc\Parser\Tag\StringTagParser;
@@ -64,6 +63,7 @@ private function createTags(array $blocks): array
         $result = [];
 
         foreach ($blocks as $block) {
+            // TODO Add an internal exception handling
             $result[] = $this->tags->parse($block, $this->descriptions);
         }
 
@@ -72,21 +72,17 @@ private function createTags(array $blocks): array
 
     private function tryCreateDescription(string $description): ?DescriptionInterface
     {
+        // TODO Add an internal exception handling
         return $this->descriptions->tryParse($description);
     }
 
     public function parse(#[Language('InjectablePHP')] string $docblock): DocBlock
     {
-        $map = new SourceMap();
-
         $current = '';
         $blocks = [];
 
         foreach ($this->splitter->split($docblock) as $segment) {
-            $text = $segment->text;
-            $offset = $segment->offset;
-
-            $map->addMapping($text, $offset);
+            $segmentText = $segment->text;
 
             // A segment starting with "@" opens a new tag section, flushing
             // whatever was accumulated for the previous one.
@@ -95,7 +91,7 @@ public function parse(#[Language('InjectablePHP')] string $docblock): DocBlock
                 $current = '';
             }
 
-            $current .= $text;
+            $current .= $segmentText;
         }
 
         $blocks[] = $current;

libs/phpdoc/src/Exception/TagParsingException.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDoc\Exception;
+
+final class TagParsingException extends ParsingException
+{
+    /**
+     * @param int<0, max> $offset
+     */
+    public static function becauseInternalErrorOccurs(
+        \Throwable $previous,
+        string $source,
+        int $offset = 0,
+    ): self {
+        return new self(
+            source: $source,
+            offset: $offset,
+            message: $previous->getMessage(),
+            previous: $previous,
+        );
+    }
+}

libs/phpdoc/src/Parser/Analyzer.php

@@ -4,7 +4,6 @@
 
 namespace TypeLang\PhpDoc\Parser;
 
-use TypeLang\PhpDoc\DocBlock\Description\DescriptionInterface;
 use TypeLang\PhpDoc\DocBlock\DocBlock;
 use TypeLang\PhpDoc\DocBlock\Tag\TagInterface;
 use TypeLang\PhpDoc\Exception\ParsingExceptionInterface;
@@ -54,7 +53,7 @@ public function analyze(string $docblock): DocBlock
 
         return new DocBlock(
             // The first section is always the description; the rest are tags.
-            description: $this->tryCreateDescription(\array_shift($blocks)),
+            description: $this->descriptions->tryParse(\array_shift($blocks)),
             tags: $this->createTags($blocks),
         );
     }
@@ -74,9 +73,4 @@ private function createTags(array $blocks): array
 
         return $result;
     }
-
-    private function tryCreateDescription(string $description): ?DescriptionInterface
-    {
-        return $this->descriptions->tryParse($description);
-    }
 }

libs/phpdoc/src/Parser/Description/BalancedBraceAwareParser.php

@@ -84,6 +84,7 @@ private function getComponents(string $description): array
 
             // Strip the outer braces: "{@see X}" becomes "@see X".
             $definition = \substr($description, $open + 1, $close - $open - 1);
+            // TODO Add an internal exception handling
             $tag = $this->tags->parse($definition, $this);
 
             // A "{@...}" with an unreadable tag name is not a tag at all: keep