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 }
|