annotate vendor/phpdocumentor/reflection-docblock/src/DocBlock/Description.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\DocBlock;
Chris@12 14
Chris@12 15 use phpDocumentor\Reflection\DocBlock\Tags\Formatter;
Chris@12 16 use phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter;
Chris@12 17 use Webmozart\Assert\Assert;
Chris@12 18
Chris@12 19 /**
Chris@12 20 * Object representing to description for a DocBlock.
Chris@12 21 *
Chris@12 22 * A Description object can consist of plain text but can also include tags. A Description Formatter can then combine
Chris@12 23 * a body template with sprintf-style placeholders together with formatted tags in order to reconstitute a complete
Chris@12 24 * description text using the format that you would prefer.
Chris@12 25 *
Chris@12 26 * Because parsing a Description text can be a verbose process this is handled by the {@see DescriptionFactory}. It is
Chris@12 27 * thus recommended to use that to create a Description object, like this:
Chris@12 28 *
Chris@12 29 * $description = $descriptionFactory->create('This is a {@see Description}', $context);
Chris@12 30 *
Chris@12 31 * The description factory will interpret the given body and create a body template and list of tags from them, and pass
Chris@12 32 * that onto the constructor if this class.
Chris@12 33 *
Chris@12 34 * > The $context variable is a class of type {@see \phpDocumentor\Reflection\Types\Context} and contains the namespace
Chris@12 35 * > and the namespace aliases that apply to this DocBlock. These are used by the Factory to resolve and expand partial
Chris@12 36 * > type names and FQSENs.
Chris@12 37 *
Chris@12 38 * If you do not want to use the DescriptionFactory you can pass a body template and tag listing like this:
Chris@12 39 *
Chris@12 40 * $description = new Description(
Chris@12 41 * 'This is a %1$s',
Chris@12 42 * [ new See(new Fqsen('\phpDocumentor\Reflection\DocBlock\Description')) ]
Chris@12 43 * );
Chris@12 44 *
Chris@12 45 * It is generally recommended to use the Factory as that will also apply escaping rules, while the Description object
Chris@12 46 * is mainly responsible for rendering.
Chris@12 47 *
Chris@12 48 * @see DescriptionFactory to create a new Description.
Chris@12 49 * @see Description\Formatter for the formatting of the body and tags.
Chris@12 50 */
Chris@12 51 class Description
Chris@12 52 {
Chris@12 53 /** @var string */
Chris@12 54 private $bodyTemplate;
Chris@12 55
Chris@12 56 /** @var Tag[] */
Chris@12 57 private $tags;
Chris@12 58
Chris@12 59 /**
Chris@12 60 * Initializes a Description with its body (template) and a listing of the tags used in the body template.
Chris@12 61 *
Chris@12 62 * @param string $bodyTemplate
Chris@12 63 * @param Tag[] $tags
Chris@12 64 */
Chris@12 65 public function __construct($bodyTemplate, array $tags = [])
Chris@12 66 {
Chris@12 67 Assert::string($bodyTemplate);
Chris@12 68
Chris@12 69 $this->bodyTemplate = $bodyTemplate;
Chris@12 70 $this->tags = $tags;
Chris@12 71 }
Chris@12 72
Chris@12 73 /**
Chris@12 74 * Returns the tags for this DocBlock.
Chris@12 75 *
Chris@12 76 * @return Tag[]
Chris@12 77 */
Chris@12 78 public function getTags()
Chris@12 79 {
Chris@12 80 return $this->tags;
Chris@12 81 }
Chris@12 82
Chris@12 83 /**
Chris@12 84 * Renders this description as a string where the provided formatter will format the tags in the expected string
Chris@12 85 * format.
Chris@12 86 *
Chris@12 87 * @param Formatter|null $formatter
Chris@12 88 *
Chris@12 89 * @return string
Chris@12 90 */
Chris@12 91 public function render(Formatter $formatter = null)
Chris@12 92 {
Chris@12 93 if ($formatter === null) {
Chris@12 94 $formatter = new PassthroughFormatter();
Chris@12 95 }
Chris@12 96
Chris@12 97 $tags = [];
Chris@12 98 foreach ($this->tags as $tag) {
Chris@12 99 $tags[] = '{' . $formatter->format($tag) . '}';
Chris@12 100 }
Chris@12 101
Chris@12 102 return vsprintf($this->bodyTemplate, $tags);
Chris@12 103 }
Chris@12 104
Chris@12 105 /**
Chris@12 106 * Returns a plain string representation of this description.
Chris@12 107 *
Chris@12 108 * @return string
Chris@12 109 */
Chris@12 110 public function __toString()
Chris@12 111 {
Chris@12 112 return $this->render();
Chris@12 113 }
Chris@12 114 }