Skip to content

Commit b095253

Browse files
boenrobotboenrobot
committed
Refactored all tags to have setters for all of their components;
Removed the special handling for VarTag (it's now equivalent to ParamTag); Minor doc, CS and coverage fixes.
1 parent c279604 commit b095253

25 files changed

+478
-263
lines changed

‎src/phpDocumentor/Reflection/DocBlock.php

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -241,7 +241,7 @@ public function getShortDescription()
241241
/**
242242
* Returns the full description or also known as long description.
243243
*
244-
* @return \phpDocumentor\Reflection\DocBlock\LongDescription
244+
* @return DocBlock\Description
245245
*/
246246
public function getLongDescription()
247247
{
@@ -271,7 +271,7 @@ public function getLocation()
271271
/**
272272
* Returns the tags for this DocBlock.
273273
*
274-
* @return \phpDocumentor\Reflection\DocBlock\Tag[]
274+
* @return DocBlock\Tag[]
275275
*/
276276
public function getTags()
277277
{
@@ -284,13 +284,13 @@ public function getTags()
284284
*
285285
* @param string $name String to search by.
286286
*
287-
* @return \phpDocumentor\Reflection\DocBlock_Tag[]
287+
* @return DocBlock\Tag[]
288288
*/
289289
public function getTagsByName($name)
290290
{
291291
$result = array();
292292

293-
/** @var \phpDocumentor\Reflection\DocBlock\Tag $tag */
293+
/** @var DocBlock\Tag $tag */
294294
foreach ($this->getTags() as $tag) {
295295
if ($tag->getName() != $name) {
296296
continue;
@@ -311,7 +311,7 @@ public function getTagsByName($name)
311311
*/
312312
public function hasTag($name)
313313
{
314-
/** @var \phpDocumentor\Reflection\DocBlock\Tag $tag */
314+
/** @var DocBlock\Tag $tag */
315315
foreach ($this->getTags() as $tag) {
316316
if ($tag->getName() == $name) {
317317
return true;

‎src/phpDocumentor/Reflection/DocBlock/Description.php

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,6 @@ class Description implements \Reflector
2929
/** @var array The contents, as an array of strings and Tag objects. */
3030
protected $parsedContents = null;
3131

32-
/** @var \phpDocumentor\Reflection\DocBlock\Tags[] */
33-
protected $tags = array();
34-
3532
/** @var DocBlock The DocBlock which this description belongs to. */
3633
protected $docblock = null;
3734

‎src/phpDocumentor/Reflection/DocBlock/Tag.php

Lines changed: 123 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,27 @@
2323
*/
2424
class Tag implements \Reflector
2525
{
26+
/**
27+
* PCRE regular expression matching a tag name.
28+
*/
29+
const REGEX_TAGNAME = '[\w\-\_\\\\]+';
30+
2631
/** @var string Name of the tag */
2732
protected $tag = '';
2833

29-
/** @var string Content of the tag */
34+
/**
35+
* @var string|null Content of the tag.
36+
* When set to NULL, it means it needs to be regenerated.
37+
*/
3038
protected $content = '';
3139

3240
/** @var string Description of the content of this tag */
3341
protected $description = '';
3442

35-
/** @var array The description, as an array of strings and Tag objects. */
43+
/**
44+
* @var array|null The description, as an array of strings and Tag objects.
45+
* When set to NULL, it means it needs to be regenerated.
46+
*/
3647
protected $parsedDescription = null;
3748

3849
/** @var Location Location of the tag. */
@@ -104,7 +115,7 @@ final public static function createInstance(
104115
Location $location = null
105116
) {
106117
if (!preg_match(
107-
'/^@([\w\-\_\\\\]+)(?:\s*([^\s].*)|$)?/us',
118+
'/^@(' . self::REGEX_TAGNAME . ')(?:\s*([^\s].*)|$)?/us',
108119
$tag_line,
109120
$matches
110121
)) {
@@ -173,46 +184,86 @@ final public static function registerTagHandler($tag, $handler)
173184
/**
174185
* Parses a tag and populates the member variables.
175186
*
176-
* @param string $type Name of the tag.
187+
* @param string $name Name of the tag.
177188
* @param string $content The contents of the given tag.
178189
* @param DocBlock $docblock The DocBlock which this tag belongs to.
179190
* @param Location $location Location of the tag.
180191
*/
181192
public function __construct(
182-
$type,
193+
$name,
183194
$content,
184195
DocBlock $docblock = null,
185196
Location $location = null
186197
) {
187-
$this->tag = $type;
188-
$this->content = $content;
189-
$this->description = trim($content);
190-
$this->docblock = $docblock;
191-
$this->location = $location;
198+
$this
199+
->setName($name)
200+
->setContent($content)
201+
->setDocBlock($docblock)
202+
->setLocation($location);
192203
}
193204

194205
/**
195-
* Returns the name of this tag.
206+
* Gets the name of this tag.
196207
*
197-
* @return string
208+
* @return string The name of this tag.
198209
*/
199210
public function getName()
200211
{
201212
return $this->tag;
202213
}
203214

204215
/**
205-
* Returns the content of this tag.
216+
* Sets the name of this tag.
217+
*
218+
* @param string $name The new name of this tag.
219+
*
220+
* @return $this
221+
* @throws \InvalidArgumentException When an invalid tag name is provided.
222+
*/
223+
public function setName($name)
224+
{
225+
if (!preg_match('/^' . self::REGEX_TAGNAME . '$/u', $name)) {
226+
throw new \InvalidArgumentException(
227+
'Invalid tag name supplied: ' . $name
228+
);
229+
}
230+
231+
$this->tag = $name;
232+
233+
return $this;
234+
}
235+
236+
/**
237+
* Gets the content of this tag.
206238
*
207239
* @return string
208240
*/
209241
public function getContent()
210242
{
243+
if (null === $this->content) {
244+
$this->content = $this->description;
245+
}
246+
211247
return $this->content;
212248
}
213249

214250
/**
215-
* Returns the description component of this tag.
251+
* Sets the content of this tag.
252+
*
253+
* @param string $content The new content of this tag.
254+
*
255+
* @return $this
256+
*/
257+
public function setContent($content)
258+
{
259+
$this->setDescription($content);
260+
$this->content = $content;
261+
262+
return $this;
263+
}
264+
265+
/**
266+
* Gets the description component of this tag.
216267
*
217268
* @return string
218269
*/
@@ -222,7 +273,23 @@ public function getDescription()
222273
}
223274

224275
/**
225-
* Returns the parsed text of this description.
276+
* Sets the description component of this tag.
277+
*
278+
* @param string $description The new description component of this tag.
279+
*
280+
* @return $this
281+
*/
282+
public function setDescription($description)
283+
{
284+
$this->content = null;
285+
$this->parsedDescription = null;
286+
$this->description = trim($description);
287+
288+
return $this;
289+
}
290+
291+
/**
292+
* Gets the parsed text of this description.
226293
*
227294
* @return array An array of strings and tag objects, in the order they
228295
* occur within the description.
@@ -237,14 +304,53 @@ public function getParsedDescription()
237304
}
238305

239306
/**
240-
* Get the location of the tag.
307+
* Gets the docblock this tag belongs to.
308+
*
309+
* @return DocBlock The docblock this tag belongs to.
310+
*/
311+
public function getDocBlock()
312+
{
313+
return $this->docblock;
314+
}
315+
316+
/**
317+
* Sets the docblock this tag belongs to.
318+
*
319+
* @param DocBlock $docblock The new docblock this tag belongs to. Setting
320+
* NULL removes any association.
321+
*
322+
* @return $this
323+
*/
324+
public function setDocBlock(DocBlock $docblock = null)
325+
{
326+
$this->docblock = $docblock;
327+
328+
return $this;
329+
}
330+
331+
/**
332+
* Gets the location of the tag.
241333
*
242-
* @return Location Tag's location.
334+
* @return Location The tag's location.
243335
*/
244336
public function getLocation()
245337
{
246338
return $this->location;
247339
}
340+
341+
/**
342+
* Sets the location of the tag.
343+
*
344+
* @param Location $location The new location of the tag.
345+
*
346+
* @return $this
347+
*/
348+
public function setLocation(Location $location = null)
349+
{
350+
$this->location = $location;
351+
352+
return $this;
353+
}
248354

249355
/**
250356
* Builds a string representation of this object.

‎src/phpDocumentor/Reflection/DocBlock/Tag/AuthorTag.php

Lines changed: 55 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212

1313
namespace phpDocumentor\Reflection\DocBlock\Tag;
1414

15-
use phpDocumentor\Reflection\DocBlock;
1615
use phpDocumentor\Reflection\DocBlock\Tag;
1716

1817
/**
@@ -25,36 +24,41 @@
2524
class AuthorTag extends Tag
2625
{
2726
/** @var string The name of the author */
28-
protected $name = '';
27+
protected $authorName = '';
2928

3029
/** @var string The email of the author */
31-
protected $email = '';
30+
protected $authorEmail = '';
31+
32+
public function getContent()
33+
{
34+
if (null === $this->content) {
35+
$this->content = $this->authorName;
36+
if ('' != $this->authorEmail) {
37+
$this->content .= "<{$this->authorEmail}>";
38+
}
39+
}
40+
41+
return $this->content;
42+
}
3243

3344
/**
34-
* Parses a tag and populates the member variables.
35-
*
36-
* @param string $type Tag identifier for this tag (should be 'author').
37-
* @param string $content Contents for this tag.
38-
* @param DocBlock $docblock The DocBlock which this tag belongs to.
39-
* @param Location $location Location of the tag.
45+
* {@inheritdoc}
4046
*/
41-
public function __construct(
42-
$type,
43-
$content,
44-
DocBlock $docblock = null,
45-
Location $location = null
46-
) {
47-
parent::__construct($type, $content, $docblock, $location);
47+
public function setContent($content)
48+
{
49+
parent::setContent($content);
4850
if (preg_match(
49-
'/^([^\<]*)(\<([^\>]*)\>)?$/',
51+
'/^([^\<]*)(\<([^\>]*)\>)?$/u',
5052
$this->description,
5153
$matches
5254
)) {
53-
$this->name = trim($matches[1]);
55+
$this->authorName = trim($matches[1]);
5456
if (isset($matches[3])) {
55-
$this->email = trim($matches[3]);
57+
$this->authorEmail = trim($matches[3]);
5658
}
5759
}
60+
61+
return $this;
5862
}
5963

6064
/**
@@ -64,7 +68,22 @@ public function __construct(
6468
*/
6569
public function getAuthorName()
6670
{
67-
return $this->name;
71+
return $this->authorName;
72+
}
73+
74+
/**
75+
* Sets the author's name.
76+
*
77+
* @param string $authorName The new author name.
78+
*
79+
* @return $this
80+
*/
81+
public function setAuthorName($authorName)
82+
{
83+
$this->content = null;
84+
$this->authorName = $authorName;
85+
86+
return $this;
6887
}
6988

7089
/**
@@ -74,6 +93,21 @@ public function getAuthorName()
7493
*/
7594
public function getAuthorEmail()
7695
{
77-
return $this->email;
96+
return $this->authorEmail;
97+
}
98+
99+
/**
100+
* Sets the author's email.
101+
*
102+
* @param string $authorEmail The new author email.
103+
*
104+
* @return $this
105+
*/
106+
public function setAuthorEmail($authorEmail)
107+
{
108+
$this->content = null;
109+
$this->authorEmail = $authorEmail;
110+
111+
return $this;
78112
}
79113
}

0 commit comments

Comments
 (0)