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;
|
Chris@12
|
16 use Webmozart\Assert\Assert;
|
Chris@12
|
17
|
Chris@12
|
18 /**
|
Chris@12
|
19 * Converts a DocBlock back from an object to a complete DocComment including Asterisks.
|
Chris@12
|
20 */
|
Chris@12
|
21 class Serializer
|
Chris@12
|
22 {
|
Chris@12
|
23 /** @var string The string to indent the comment with. */
|
Chris@12
|
24 protected $indentString = ' ';
|
Chris@12
|
25
|
Chris@12
|
26 /** @var int The number of times the indent string is repeated. */
|
Chris@12
|
27 protected $indent = 0;
|
Chris@12
|
28
|
Chris@12
|
29 /** @var bool Whether to indent the first line with the given indent amount and string. */
|
Chris@12
|
30 protected $isFirstLineIndented = true;
|
Chris@12
|
31
|
Chris@12
|
32 /** @var int|null The max length of a line. */
|
Chris@12
|
33 protected $lineLength = null;
|
Chris@12
|
34
|
Chris@12
|
35 /** @var DocBlock\Tags\Formatter A custom tag formatter. */
|
Chris@12
|
36 protected $tagFormatter = null;
|
Chris@12
|
37
|
Chris@12
|
38 /**
|
Chris@12
|
39 * Create a Serializer instance.
|
Chris@12
|
40 *
|
Chris@12
|
41 * @param int $indent The number of times the indent string is repeated.
|
Chris@12
|
42 * @param string $indentString The string to indent the comment with.
|
Chris@12
|
43 * @param bool $indentFirstLine Whether to indent the first line.
|
Chris@12
|
44 * @param int|null $lineLength The max length of a line or NULL to disable line wrapping.
|
Chris@12
|
45 * @param DocBlock\Tags\Formatter $tagFormatter A custom tag formatter, defaults to PassthroughFormatter.
|
Chris@12
|
46 */
|
Chris@12
|
47 public function __construct($indent = 0, $indentString = ' ', $indentFirstLine = true, $lineLength = null, $tagFormatter = null)
|
Chris@12
|
48 {
|
Chris@12
|
49 Assert::integer($indent);
|
Chris@12
|
50 Assert::string($indentString);
|
Chris@12
|
51 Assert::boolean($indentFirstLine);
|
Chris@12
|
52 Assert::nullOrInteger($lineLength);
|
Chris@12
|
53 Assert::nullOrIsInstanceOf($tagFormatter, 'phpDocumentor\Reflection\DocBlock\Tags\Formatter');
|
Chris@12
|
54
|
Chris@12
|
55 $this->indent = $indent;
|
Chris@12
|
56 $this->indentString = $indentString;
|
Chris@12
|
57 $this->isFirstLineIndented = $indentFirstLine;
|
Chris@12
|
58 $this->lineLength = $lineLength;
|
Chris@12
|
59 $this->tagFormatter = $tagFormatter ?: new DocBlock\Tags\Formatter\PassthroughFormatter();
|
Chris@12
|
60 }
|
Chris@12
|
61
|
Chris@12
|
62 /**
|
Chris@12
|
63 * Generate a DocBlock comment.
|
Chris@12
|
64 *
|
Chris@12
|
65 * @param DocBlock $docblock The DocBlock to serialize.
|
Chris@12
|
66 *
|
Chris@12
|
67 * @return string The serialized doc block.
|
Chris@12
|
68 */
|
Chris@12
|
69 public function getDocComment(DocBlock $docblock)
|
Chris@12
|
70 {
|
Chris@12
|
71 $indent = str_repeat($this->indentString, $this->indent);
|
Chris@12
|
72 $firstIndent = $this->isFirstLineIndented ? $indent : '';
|
Chris@12
|
73 // 3 === strlen(' * ')
|
Chris@12
|
74 $wrapLength = $this->lineLength ? $this->lineLength - strlen($indent) - 3 : null;
|
Chris@12
|
75
|
Chris@12
|
76 $text = $this->removeTrailingSpaces(
|
Chris@12
|
77 $indent,
|
Chris@12
|
78 $this->addAsterisksForEachLine(
|
Chris@12
|
79 $indent,
|
Chris@12
|
80 $this->getSummaryAndDescriptionTextBlock($docblock, $wrapLength)
|
Chris@12
|
81 )
|
Chris@12
|
82 );
|
Chris@12
|
83
|
Chris@12
|
84 $comment = "{$firstIndent}/**\n";
|
Chris@12
|
85 if ($text) {
|
Chris@12
|
86 $comment .= "{$indent} * {$text}\n";
|
Chris@12
|
87 $comment .= "{$indent} *\n";
|
Chris@12
|
88 }
|
Chris@12
|
89
|
Chris@12
|
90 $comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment);
|
Chris@12
|
91 $comment .= $indent . ' */';
|
Chris@12
|
92
|
Chris@12
|
93 return $comment;
|
Chris@12
|
94 }
|
Chris@12
|
95
|
Chris@12
|
96 /**
|
Chris@12
|
97 * @param $indent
|
Chris@12
|
98 * @param $text
|
Chris@12
|
99 * @return mixed
|
Chris@12
|
100 */
|
Chris@12
|
101 private function removeTrailingSpaces($indent, $text)
|
Chris@12
|
102 {
|
Chris@12
|
103 return str_replace("\n{$indent} * \n", "\n{$indent} *\n", $text);
|
Chris@12
|
104 }
|
Chris@12
|
105
|
Chris@12
|
106 /**
|
Chris@12
|
107 * @param $indent
|
Chris@12
|
108 * @param $text
|
Chris@12
|
109 * @return mixed
|
Chris@12
|
110 */
|
Chris@12
|
111 private function addAsterisksForEachLine($indent, $text)
|
Chris@12
|
112 {
|
Chris@12
|
113 return str_replace("\n", "\n{$indent} * ", $text);
|
Chris@12
|
114 }
|
Chris@12
|
115
|
Chris@12
|
116 /**
|
Chris@12
|
117 * @param DocBlock $docblock
|
Chris@12
|
118 * @param $wrapLength
|
Chris@12
|
119 * @return string
|
Chris@12
|
120 */
|
Chris@12
|
121 private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLength)
|
Chris@12
|
122 {
|
Chris@12
|
123 $text = $docblock->getSummary() . ((string)$docblock->getDescription() ? "\n\n" . $docblock->getDescription()
|
Chris@12
|
124 : '');
|
Chris@12
|
125 if ($wrapLength !== null) {
|
Chris@12
|
126 $text = wordwrap($text, $wrapLength);
|
Chris@12
|
127 return $text;
|
Chris@12
|
128 }
|
Chris@12
|
129
|
Chris@12
|
130 return $text;
|
Chris@12
|
131 }
|
Chris@12
|
132
|
Chris@12
|
133 /**
|
Chris@12
|
134 * @param DocBlock $docblock
|
Chris@12
|
135 * @param $wrapLength
|
Chris@12
|
136 * @param $indent
|
Chris@12
|
137 * @param $comment
|
Chris@12
|
138 * @return string
|
Chris@12
|
139 */
|
Chris@12
|
140 private function addTagBlock(DocBlock $docblock, $wrapLength, $indent, $comment)
|
Chris@12
|
141 {
|
Chris@12
|
142 foreach ($docblock->getTags() as $tag) {
|
Chris@12
|
143 $tagText = $this->tagFormatter->format($tag);
|
Chris@12
|
144 if ($wrapLength !== null) {
|
Chris@12
|
145 $tagText = wordwrap($tagText, $wrapLength);
|
Chris@12
|
146 }
|
Chris@12
|
147
|
Chris@12
|
148 $tagText = str_replace("\n", "\n{$indent} * ", $tagText);
|
Chris@12
|
149
|
Chris@12
|
150 $comment .= "{$indent} * {$tagText}\n";
|
Chris@12
|
151 }
|
Chris@12
|
152
|
Chris@12
|
153 return $comment;
|
Chris@12
|
154 }
|
Chris@12
|
155 }
|