annotate vendor/phpdocumentor/reflection-docblock/src/DocBlock.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 7a779792577d
children
rev   line source
Chris@12 1 <?php
Chris@12 2 /**
Chris@12 3 * This file is part of phpDocumentor.
Chris@12 4 *
Chris@12 5 * For the full copyright and license information, please view the LICENSE
Chris@12 6 * file that was distributed with this source code.
Chris@12 7 *
Chris@12 8 * @copyright 2010-2015 Mike van Riel<mike@phpdoc.org>
Chris@12 9 * @license http://www.opensource.org/licenses/mit-license.php MIT
Chris@12 10 * @link http://phpdoc.org
Chris@12 11 */
Chris@12 12
Chris@12 13 namespace phpDocumentor\Reflection;
Chris@12 14
Chris@12 15 use phpDocumentor\Reflection\DocBlock\Tag;
Chris@12 16 use Webmozart\Assert\Assert;
Chris@12 17
Chris@12 18 final class DocBlock
Chris@12 19 {
Chris@12 20 /** @var string The opening line for this docblock. */
Chris@12 21 private $summary = '';
Chris@12 22
Chris@12 23 /** @var DocBlock\Description The actual description for this docblock. */
Chris@12 24 private $description = null;
Chris@12 25
Chris@12 26 /** @var Tag[] An array containing all the tags in this docblock; except inline. */
Chris@12 27 private $tags = [];
Chris@12 28
Chris@12 29 /** @var Types\Context Information about the context of this DocBlock. */
Chris@12 30 private $context = null;
Chris@12 31
Chris@12 32 /** @var Location Information about the location of this DocBlock. */
Chris@12 33 private $location = null;
Chris@12 34
Chris@12 35 /** @var bool Is this DocBlock (the start of) a template? */
Chris@12 36 private $isTemplateStart = false;
Chris@12 37
Chris@12 38 /** @var bool Does this DocBlock signify the end of a DocBlock template? */
Chris@12 39 private $isTemplateEnd = false;
Chris@12 40
Chris@12 41 /**
Chris@12 42 * @param string $summary
Chris@12 43 * @param DocBlock\Description $description
Chris@12 44 * @param DocBlock\Tag[] $tags
Chris@12 45 * @param Types\Context $context The context in which the DocBlock occurs.
Chris@12 46 * @param Location $location The location within the file that this DocBlock occurs in.
Chris@12 47 * @param bool $isTemplateStart
Chris@12 48 * @param bool $isTemplateEnd
Chris@12 49 */
Chris@12 50 public function __construct(
Chris@12 51 $summary = '',
Chris@12 52 DocBlock\Description $description = null,
Chris@12 53 array $tags = [],
Chris@12 54 Types\Context $context = null,
Chris@12 55 Location $location = null,
Chris@12 56 $isTemplateStart = false,
Chris@12 57 $isTemplateEnd = false
Chris@12 58 ) {
Chris@12 59 Assert::string($summary);
Chris@12 60 Assert::boolean($isTemplateStart);
Chris@12 61 Assert::boolean($isTemplateEnd);
Chris@12 62 Assert::allIsInstanceOf($tags, Tag::class);
Chris@12 63
Chris@12 64 $this->summary = $summary;
Chris@12 65 $this->description = $description ?: new DocBlock\Description('');
Chris@12 66 foreach ($tags as $tag) {
Chris@12 67 $this->addTag($tag);
Chris@12 68 }
Chris@12 69
Chris@12 70 $this->context = $context;
Chris@12 71 $this->location = $location;
Chris@12 72
Chris@12 73 $this->isTemplateEnd = $isTemplateEnd;
Chris@12 74 $this->isTemplateStart = $isTemplateStart;
Chris@12 75 }
Chris@12 76
Chris@12 77 /**
Chris@12 78 * @return string
Chris@12 79 */
Chris@12 80 public function getSummary()
Chris@12 81 {
Chris@12 82 return $this->summary;
Chris@12 83 }
Chris@12 84
Chris@12 85 /**
Chris@12 86 * @return DocBlock\Description
Chris@12 87 */
Chris@12 88 public function getDescription()
Chris@12 89 {
Chris@12 90 return $this->description;
Chris@12 91 }
Chris@12 92
Chris@12 93 /**
Chris@12 94 * Returns the current context.
Chris@12 95 *
Chris@12 96 * @return Types\Context
Chris@12 97 */
Chris@12 98 public function getContext()
Chris@12 99 {
Chris@12 100 return $this->context;
Chris@12 101 }
Chris@12 102
Chris@12 103 /**
Chris@12 104 * Returns the current location.
Chris@12 105 *
Chris@12 106 * @return Location
Chris@12 107 */
Chris@12 108 public function getLocation()
Chris@12 109 {
Chris@12 110 return $this->location;
Chris@12 111 }
Chris@12 112
Chris@12 113 /**
Chris@12 114 * Returns whether this DocBlock is the start of a Template section.
Chris@12 115 *
Chris@12 116 * A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker
Chris@12 117 * (`#@+`) that is appended directly after the opening `/**` of a DocBlock.
Chris@12 118 *
Chris@12 119 * An example of such an opening is:
Chris@12 120 *
Chris@12 121 * ```
Chris@12 122 * /**#@+
Chris@12 123 * * My DocBlock
Chris@12 124 * * /
Chris@12 125 * ```
Chris@12 126 *
Chris@12 127 * The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all
Chris@12 128 * elements that follow until another DocBlock is found that contains the closing marker (`#@-`).
Chris@12 129 *
Chris@12 130 * @see self::isTemplateEnd() for the check whether a closing marker was provided.
Chris@12 131 *
Chris@12 132 * @return boolean
Chris@12 133 */
Chris@12 134 public function isTemplateStart()
Chris@12 135 {
Chris@12 136 return $this->isTemplateStart;
Chris@12 137 }
Chris@12 138
Chris@12 139 /**
Chris@12 140 * Returns whether this DocBlock is the end of a Template section.
Chris@12 141 *
Chris@12 142 * @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
Chris@12 143 *
Chris@12 144 * @return boolean
Chris@12 145 */
Chris@12 146 public function isTemplateEnd()
Chris@12 147 {
Chris@12 148 return $this->isTemplateEnd;
Chris@12 149 }
Chris@12 150
Chris@12 151 /**
Chris@12 152 * Returns the tags for this DocBlock.
Chris@12 153 *
Chris@12 154 * @return Tag[]
Chris@12 155 */
Chris@12 156 public function getTags()
Chris@12 157 {
Chris@12 158 return $this->tags;
Chris@12 159 }
Chris@12 160
Chris@12 161 /**
Chris@12 162 * Returns an array of tags matching the given name. If no tags are found
Chris@12 163 * an empty array is returned.
Chris@12 164 *
Chris@12 165 * @param string $name String to search by.
Chris@12 166 *
Chris@12 167 * @return Tag[]
Chris@12 168 */
Chris@12 169 public function getTagsByName($name)
Chris@12 170 {
Chris@12 171 Assert::string($name);
Chris@12 172
Chris@12 173 $result = [];
Chris@12 174
Chris@12 175 /** @var Tag $tag */
Chris@12 176 foreach ($this->getTags() as $tag) {
Chris@12 177 if ($tag->getName() !== $name) {
Chris@12 178 continue;
Chris@12 179 }
Chris@12 180
Chris@12 181 $result[] = $tag;
Chris@12 182 }
Chris@12 183
Chris@12 184 return $result;
Chris@12 185 }
Chris@12 186
Chris@12 187 /**
Chris@12 188 * Checks if a tag of a certain type is present in this DocBlock.
Chris@12 189 *
Chris@12 190 * @param string $name Tag name to check for.
Chris@12 191 *
Chris@12 192 * @return bool
Chris@12 193 */
Chris@12 194 public function hasTag($name)
Chris@12 195 {
Chris@12 196 Assert::string($name);
Chris@12 197
Chris@12 198 /** @var Tag $tag */
Chris@12 199 foreach ($this->getTags() as $tag) {
Chris@12 200 if ($tag->getName() === $name) {
Chris@12 201 return true;
Chris@12 202 }
Chris@12 203 }
Chris@12 204
Chris@12 205 return false;
Chris@12 206 }
Chris@12 207
Chris@12 208 /**
Chris@12 209 * Remove a tag from this DocBlock.
Chris@12 210 *
Chris@12 211 * @param Tag $tag The tag to remove.
Chris@12 212 *
Chris@12 213 * @return void
Chris@12 214 */
Chris@12 215 public function removeTag(Tag $tagToRemove)
Chris@12 216 {
Chris@12 217 foreach ($this->tags as $key => $tag) {
Chris@12 218 if ($tag === $tagToRemove) {
Chris@12 219 unset($this->tags[$key]);
Chris@12 220 break;
Chris@12 221 }
Chris@12 222 }
Chris@12 223 }
Chris@12 224
Chris@12 225 /**
Chris@12 226 * Adds a tag to this DocBlock.
Chris@12 227 *
Chris@12 228 * @param Tag $tag The tag to add.
Chris@12 229 *
Chris@12 230 * @return void
Chris@12 231 */
Chris@12 232 private function addTag(Tag $tag)
Chris@12 233 {
Chris@12 234 $this->tags[] = $tag;
Chris@12 235 }
Chris@12 236 }