about summary refs log tree commit diff stats
path: root/vendor/phpdocumentor/reflection-docblock/src/DocBlock.php
diff options
context:
space:
mode:
authorfox <fox@fakecake.org>2026-05-26 06:45:47 +0300
committerfox <fox@fakecake.org>2026-05-26 06:45:47 +0300
commit4ce7212e8c26cd613db0cfc75ef8a5a0ba6eb7be (patch)
tree0ec2e37f6f86d59a904a2f1de2a15294ef1ae349 /vendor/phpdocumentor/reflection-docblock/src/DocBlock.php
parentcae514dddfc59f533a93a47afc283371d5949843 (diff)
parentdc60880d9cc4074a231fd21c9508d0f78beaf1f1 (diff)
downloadthe-epube-4ce7212e8c26cd613db0cfc75ef8a5a0ba6eb7be.tar.gz
the-epube-4ce7212e8c26cd613db0cfc75ef8a5a0ba6eb7be.tar.xz
Merge branch 'dev' into 'master'
Dev

See merge request git/the-epube!39
Diffstat (limited to 'vendor/phpdocumentor/reflection-docblock/src/DocBlock.php')
-rw-r--r--vendor/phpdocumentor/reflection-docblock/src/DocBlock.php228
1 files changed, 228 insertions, 0 deletions
diff --git a/vendor/phpdocumentor/reflection-docblock/src/DocBlock.php b/vendor/phpdocumentor/reflection-docblock/src/DocBlock.php
new file mode 100644
index 0000000..90d8066
--- /dev/null
+++ b/vendor/phpdocumentor/reflection-docblock/src/DocBlock.php
@@ -0,0 +1,228 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection;
+
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Tags\TagWithType;
+use Webmozart\Assert\Assert;
+
+final class DocBlock
+{
+    /** @var string The opening line for this docblock. */
+    private string $summary;
+
+    /** @var DocBlock\Description The actual description for this docblock. */
+    private DocBlock\Description $description;
+
+    /** @var Tag[] An array containing all the tags in this docblock; except inline. */
+    private array $tags = [];
+
+    /** @var Types\Context|null Information about the context of this DocBlock. */
+    private ?Types\Context $context = null;
+
+    /** @var Location|null Information about the location of this DocBlock. */
+    private ?Location $location = null;
+
+    /** @var bool Is this DocBlock (the start of) a template? */
+    private bool $isTemplateStart;
+
+    /** @var bool Does this DocBlock signify the end of a DocBlock template? */
+    private bool $isTemplateEnd;
+
+    /**
+     * @param DocBlock\Tag[] $tags
+     * @param Types\Context  $context  The context in which the DocBlock occurs.
+     * @param Location       $location The location within the file that this DocBlock occurs in.
+     */
+    public function __construct(
+        string $summary = '',
+        ?DocBlock\Description $description = null,
+        array $tags = [],
+        ?Types\Context $context = null,
+        ?Location $location = null,
+        bool $isTemplateStart = false,
+        bool $isTemplateEnd = false
+    ) {
+        Assert::allIsInstanceOf($tags, Tag::class);
+
+        $this->summary     = $summary;
+        $this->description = $description ?: new DocBlock\Description('');
+        foreach ($tags as $tag) {
+            $this->addTag($tag);
+        }
+
+        $this->context  = $context;
+        $this->location = $location;
+
+        $this->isTemplateEnd   = $isTemplateEnd;
+        $this->isTemplateStart = $isTemplateStart;
+    }
+
+    public function getSummary(): string
+    {
+        return $this->summary;
+    }
+
+    public function getDescription(): DocBlock\Description
+    {
+        return $this->description;
+    }
+
+    /**
+     * Returns the current context.
+     */
+    public function getContext(): ?Types\Context
+    {
+        return $this->context;
+    }
+
+    /**
+     * Returns the current location.
+     */
+    public function getLocation(): ?Location
+    {
+        return $this->location;
+    }
+
+    /**
+     * Returns whether this DocBlock is the start of a Template section.
+     *
+     * A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker
+     * (`#@+`) that is appended directly after the opening `/**` of a DocBlock.
+     *
+     * An example of such an opening is:
+     *
+     * ```
+     * /**#@+
+     *  * My DocBlock
+     *  * /
+     * ```
+     *
+     * The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all
+     * elements that follow until another DocBlock is found that contains the closing marker (`#@-`).
+     *
+     * @see self::isTemplateEnd() for the check whether a closing marker was provided.
+     */
+    public function isTemplateStart(): bool
+    {
+        return $this->isTemplateStart;
+    }
+
+    /**
+     * Returns whether this DocBlock is the end of a Template section.
+     *
+     * @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
+     */
+    public function isTemplateEnd(): bool
+    {
+        return $this->isTemplateEnd;
+    }
+
+    /**
+     * Returns the tags for this DocBlock.
+     *
+     * @return Tag[]
+     */
+    public function getTags(): array
+    {
+        return $this->tags;
+    }
+
+    /**
+     * Returns an array of tags matching the given name. If no tags are found
+     * an empty array is returned.
+     *
+     * @param string $name String to search by.
+     *
+     * @return Tag[]
+     */
+    public function getTagsByName(string $name): array
+    {
+        $result = [];
+
+        foreach ($this->getTags() as $tag) {
+            if ($tag->getName() !== $name) {
+                continue;
+            }
+
+            $result[] = $tag;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Returns an array of tags with type matching the given name. If no tags are found
+     * an empty array is returned.
+     *
+     * @param string $name String to search by.
+     *
+     * @return TagWithType[]
+     */
+    public function getTagsWithTypeByName(string $name): array
+    {
+        $result = [];
+
+        foreach ($this->getTagsByName($name) as $tag) {
+            if (!$tag instanceof TagWithType) {
+                continue;
+            }
+
+            $result[] = $tag;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Checks if a tag of a certain type is present in this DocBlock.
+     *
+     * @param string $name Tag name to check for.
+     */
+    public function hasTag(string $name): bool
+    {
+        foreach ($this->getTags() as $tag) {
+            if ($tag->getName() === $name) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Remove a tag from this DocBlock.
+     *
+     * @param Tag $tagToRemove The tag to remove.
+     */
+    public function removeTag(Tag $tagToRemove): void
+    {
+        foreach ($this->tags as $key => $tag) {
+            if ($tag === $tagToRemove) {
+                unset($this->tags[$key]);
+                break;
+            }
+        }
+    }
+
+    /**
+     * Adds a tag to this DocBlock.
+     *
+     * @param Tag $tag The tag to add.
+     */
+    private function addTag(Tag $tag): void
+    {
+        $this->tags[] = $tag;
+    }
+}