|
1
|
|
|
<?php |
|
2
|
|
|
/** |
|
3
|
|
|
* This file is part of phpDocumentor. |
|
4
|
|
|
* |
|
5
|
|
|
* For the full copyright and license information, please view the LICENSE |
|
6
|
|
|
* file that was distributed with this source code. |
|
7
|
|
|
* |
|
8
|
|
|
* @copyright 2010-2015 Mike van Riel<[email protected]> |
|
9
|
|
|
* @license http://www.opensource.org/licenses/mit-license.php MIT |
|
10
|
|
|
* @link http://phpdoc.org |
|
11
|
|
|
*/ |
|
12
|
|
|
|
|
13
|
|
|
namespace phpDocumentor\Reflection\DocBlock; |
|
14
|
|
|
|
|
15
|
|
|
use phpDocumentor\Reflection\DocBlock; |
|
16
|
|
|
use Webmozart\Assert\Assert; |
|
17
|
|
|
|
|
18
|
|
|
/** |
|
19
|
|
|
* Converts a DocBlock back from an object to a complete DocComment including Asterisks. |
|
20
|
|
|
*/ |
|
21
|
|
|
class Serializer |
|
22
|
|
|
{ |
|
23
|
|
|
/** @var string The string to indent the comment with. */ |
|
24
|
|
|
protected $indentString = ' '; |
|
25
|
|
|
|
|
26
|
|
|
/** @var int The number of times the indent string is repeated. */ |
|
27
|
|
|
protected $indent = 0; |
|
28
|
|
|
|
|
29
|
|
|
/** @var bool Whether to indent the first line with the given indent amount and string. */ |
|
30
|
|
|
protected $isFirstLineIndented = true; |
|
31
|
|
|
|
|
32
|
|
|
/** @var int|null The max length of a line. */ |
|
33
|
|
|
protected $lineLength = null; |
|
34
|
|
|
|
|
35
|
|
|
/** |
|
36
|
|
|
* Create a Serializer instance. |
|
37
|
|
|
* |
|
38
|
|
|
* @param int $indent The number of times the indent string is repeated. |
|
39
|
|
|
* @param string $indentString The string to indent the comment with. |
|
40
|
|
|
* @param bool $indentFirstLine Whether to indent the first line. |
|
41
|
|
|
* @param int|null $lineLength The max length of a line or NULL to disable line wrapping. |
|
42
|
|
|
*/ |
|
43
|
|
|
public function __construct($indent = 0, $indentString = ' ', $indentFirstLine = true, $lineLength = null) |
|
44
|
|
|
{ |
|
45
|
|
|
Assert::integer($indent); |
|
46
|
|
|
Assert::string($indentString); |
|
47
|
|
|
Assert::boolean($indentFirstLine); |
|
48
|
|
|
Assert::nullOrInteger($lineLength); |
|
49
|
|
|
|
|
50
|
|
|
$this->indent = $indent; |
|
51
|
|
|
$this->indentString = $indentString; |
|
52
|
|
|
$this->isFirstLineIndented = $indentFirstLine; |
|
53
|
|
|
$this->lineLength = $lineLength; |
|
54
|
|
|
} |
|
55
|
|
|
|
|
56
|
|
|
/** |
|
57
|
|
|
* Generate a DocBlock comment. |
|
58
|
|
|
* |
|
59
|
|
|
* @param DocBlock $docblock The DocBlock to serialize. |
|
60
|
|
|
* |
|
61
|
|
|
* @return string The serialized doc block. |
|
62
|
|
|
*/ |
|
63
|
|
|
public function getDocComment(DocBlock $docblock) |
|
64
|
|
|
{ |
|
65
|
|
|
$indent = str_repeat($this->indentString, $this->indent); |
|
66
|
|
|
$firstIndent = $this->isFirstLineIndented ? $indent : ''; |
|
67
|
|
|
// 3 === strlen(' * ') |
|
|
|
|
|
|
68
|
|
|
$wrapLength = $this->lineLength ? $this->lineLength - strlen($indent) - 3 : null; |
|
69
|
|
|
|
|
70
|
|
|
$text = $this->removeTrailingSpaces( |
|
71
|
|
|
$indent, |
|
72
|
|
|
$this->addAsterisksForEachLine( |
|
73
|
|
|
$indent, |
|
74
|
|
|
$this->getSummaryAndDescriptionTextBlock($docblock, $wrapLength) |
|
75
|
|
|
) |
|
76
|
|
|
); |
|
77
|
|
|
|
|
78
|
|
|
$comment = "{$firstIndent}/**\n{$indent} * {$text}\n{$indent} *\n"; |
|
79
|
|
|
$comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment); |
|
80
|
|
|
$comment .= $indent . ' */'; |
|
81
|
|
|
|
|
82
|
|
|
return $comment; |
|
83
|
|
|
} |
|
84
|
|
|
|
|
85
|
|
|
/** |
|
86
|
|
|
* @param $indent |
|
87
|
|
|
* @param $text |
|
88
|
|
|
* @return mixed |
|
89
|
|
|
*/ |
|
90
|
|
|
private function removeTrailingSpaces($indent, $text) |
|
91
|
|
|
{ |
|
92
|
|
|
return str_replace("\n{$indent} * \n", "\n{$indent} *\n", $text); |
|
93
|
|
|
} |
|
94
|
|
|
|
|
95
|
|
|
/** |
|
96
|
|
|
* @param $indent |
|
97
|
|
|
* @param $text |
|
98
|
|
|
* @return mixed |
|
99
|
|
|
*/ |
|
100
|
|
|
private function addAsterisksForEachLine($indent, $text) |
|
101
|
|
|
{ |
|
102
|
|
|
return str_replace("\n", "\n{$indent} * ", $text); |
|
103
|
|
|
} |
|
104
|
|
|
|
|
105
|
|
|
/** |
|
106
|
|
|
* @param DocBlock $docblock |
|
107
|
|
|
* @param $wrapLength |
|
108
|
|
|
* @return string |
|
109
|
|
|
*/ |
|
110
|
|
|
private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLength) |
|
111
|
|
|
{ |
|
112
|
|
|
$text = $docblock->getSummary() . ((string)$docblock->getDescription() ? "\n\n" . $docblock->getDescription() |
|
113
|
|
|
: ''); |
|
114
|
|
|
if ($wrapLength !== null) { |
|
115
|
|
|
$text = wordwrap($text, $wrapLength); |
|
116
|
|
|
return $text; |
|
117
|
|
|
} |
|
118
|
|
|
return $text; |
|
119
|
|
|
} |
|
120
|
|
|
|
|
121
|
|
|
/** |
|
122
|
|
|
* @param DocBlock $docblock |
|
123
|
|
|
* @param $wrapLength |
|
124
|
|
|
* @param $indent |
|
125
|
|
|
* @param $comment |
|
126
|
|
|
* @return string |
|
127
|
|
|
*/ |
|
128
|
|
|
private function addTagBlock(DocBlock $docblock, $wrapLength, $indent, $comment) |
|
129
|
|
|
{ |
|
130
|
|
|
foreach ($docblock->getTags() as $tag) { |
|
131
|
|
|
$formatter = new DocBlock\Tags\Formatter\PassthroughFormatter(); |
|
132
|
|
|
$tagText = $formatter->format($tag); |
|
133
|
|
|
if ($wrapLength !== null) { |
|
134
|
|
|
$tagText = wordwrap($tagText, $wrapLength); |
|
135
|
|
|
} |
|
136
|
|
|
$tagText = str_replace("\n", "\n{$indent} * ", $tagText); |
|
137
|
|
|
|
|
138
|
|
|
$comment .= "{$indent} * {$tagText}\n"; |
|
139
|
|
|
} |
|
140
|
|
|
|
|
141
|
|
|
return $comment; |
|
142
|
|
|
} |
|
143
|
|
|
} |
|
144
|
|
|
|
arunfung /
laravel-package-develop
Sometimes obsolete code just ends up commented out instead of removed. In this case it is better to remove the code once you have checked you do not need it.
The code might also have been commented out for debugging purposes. In this case it is vital that someone uncomments it again or your project may behave in very unexpected ways in production.
This check looks for comments that seem to be mostly valid code and reports them.