Skip to content

Commit ffcaa03

Browse files
boenrobotboenrobot
committed
Merge pull request #12 from boenrobot/source-and-example
Reflections for @source and @example
2 parents aed654a + 37810ef commit ffcaa03

File tree

5 files changed

+479
-0
lines changed

5 files changed

+479
-0
lines changed

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ class Tag implements \Reflector
5353
=> '\phpDocumentor\Reflection\DocBlock\Tag\CoversTag',
5454
'deprecated'
5555
=> '\phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag',
56+
'example'
57+
=> '\phpDocumentor\Reflection\DocBlock\Tag\ExampleTag',
5658
'link'
5759
=> '\phpDocumentor\Reflection\DocBlock\Tag\LinkTag',
5860
'method'
@@ -71,6 +73,8 @@ class Tag implements \Reflector
7173
=> '\phpDocumentor\Reflection\DocBlock\Tag\SeeTag',
7274
'since'
7375
=> '\phpDocumentor\Reflection\DocBlock\Tag\SinceTag',
76+
'source'
77+
=> '\phpDocumentor\Reflection\DocBlock\Tag\SourceTag',
7478
'throw'
7579
=> '\phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag',
7680
'throws'

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
<?php
2+
/**
3+
* phpDocumentor
4+
*
5+
* PHP Version 5.3
6+
*
7+
* @author Vasil Rangelov <[email protected]>
8+
* @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
9+
* @license http://www.opensource.org/licenses/mit-license.php MIT
10+
* @link http://phpdoc.org
11+
*/
12+
13+
namespace phpDocumentor\Reflection\DocBlock\Tag;
14+
15+
use phpDocumentor\Reflection\DocBlock;
16+
use phpDocumentor\Reflection\DocBlock\Tag;
17+
18+
/**
19+
* Reflection class for a @example tag in a Docblock.
20+
*
21+
* @author Vasil Rangelov <[email protected]>
22+
* @license http://www.opensource.org/licenses/mit-license.php MIT
23+
* @link http://phpdoc.org
24+
*/
25+
class ExampleTag extends SourceTag
26+
{
27+
/** @var string Path to a file to use as an example. Can also be an URI. */
28+
protected $filePath = '';
29+
30+
/**
31+
* Parses a tag and populates the member variables.
32+
*
33+
* @param string $type Tag identifier for this tag (should be 'example').
34+
* @param string $content Contents for this tag.
35+
* @param DocBlock $docblock The DocBlock which this tag belongs to.
36+
*/
37+
public function __construct($type, $content, DocBlock $docblock = null)
38+
{
39+
Tag::__construct($type, $content, $docblock);
40+
if (preg_match(
41+
'/^(?:\"([^\"]+)\"|(\S+))(?:\s+(.*))?$/su',
42+
$this->description,
43+
$matches
44+
)) {
45+
if ('' !== $matches[1]) {
46+
//Quoted file path.
47+
$this->filePath = trim($matches[1]);
48+
} elseif (false === strpos($matches[2], ':')) {
49+
//Relative URL or a file path with no spaces in it.
50+
$this->filePath = rawurldecode(
51+
str_replace(array('/', '\\'), '%2F', $matches[2])
52+
);
53+
} else {
54+
//Absolute URL or URI.
55+
$this->filePath = $matches[2];
56+
}
57+
58+
if (isset($matches[3])) {
59+
parent::__construct($type, $matches[3]);
60+
$this->content = $content;
61+
} else {
62+
$this->description = '';
63+
}
64+
}
65+
}
66+
67+
/**
68+
* Returns the file path.
69+
*
70+
* @return string Path to a file to use as an example. Can also be an URI.
71+
*/
72+
public function getFilePath()
73+
{
74+
return $this->filePath;
75+
}
76+
}

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<?php
2+
/**
3+
* phpDocumentor
4+
*
5+
* PHP Version 5.3
6+
*
7+
* @author Vasil Rangelov <[email protected]>
8+
* @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
9+
* @license http://www.opensource.org/licenses/mit-license.php MIT
10+
* @link http://phpdoc.org
11+
*/
12+
13+
namespace phpDocumentor\Reflection\DocBlock\Tag;
14+
15+
use phpDocumentor\Reflection\DocBlock\Tag;
16+
17+
/**
18+
* Reflection class for a @source tag in a Docblock.
19+
*
20+
* @author Vasil Rangelov <[email protected]>
21+
* @license http://www.opensource.org/licenses/mit-license.php MIT
22+
* @link http://phpdoc.org
23+
*/
24+
class SourceTag extends Tag
25+
{
26+
/**
27+
* @var int The starting line, relative to the structural element's
28+
* location.
29+
*/
30+
protected $startingLine = 1;
31+
32+
/**
33+
* @var int|null The number of lines, relative to the starting line. NULL
34+
* means "to the end".
35+
*/
36+
protected $lineCount = null;
37+
38+
/**
39+
* Parses a tag and populates the member variables.
40+
*
41+
* @param string $type Tag identifier for this tag (should be 'source').
42+
* @param string $content Contents for this tag.
43+
* @param DocBlock $docblock The DocBlock which this tag belongs to.
44+
*/
45+
public function __construct($type, $content, DocBlock $docblock = null)
46+
{
47+
parent::__construct($type, $content, $docblock);
48+
$content = preg_split('/[\ \t]+/u', $this->description, 2);
49+
if (preg_match(
50+
'/^([1-9]\d*)\s*(?:([1-9]\d*)\s+)?(.*)$/su',
51+
$this->description,
52+
$matches
53+
)) {
54+
$this->startingLine = (int)$matches[1];
55+
if (isset($matches[2]) && '' !== $matches[2]) {
56+
$this->lineCount = (int)$matches[2];
57+
}
58+
$this->description = $matches[3];
59+
}
60+
}
61+
62+
/**
63+
* Returns the starting line.
64+
*
65+
* @return int The starting line, relative to the structural element's
66+
* location.
67+
*/
68+
public function getStartingLine()
69+
{
70+
return $this->startingLine;
71+
}
72+
73+
/**
74+
* Returns the number of lines.
75+
*
76+
* @return int|null The number of lines, relative to the starting line. NULL
77+
* means "to the end".
78+
*/
79+
public function getLineCount()
80+
{
81+
return $this->lineCount;
82+
}
83+
}

‎tests/phpDocumentor/Reflection/DocBlock/Tag/ExampleTagTest.php

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
<?php
2+
/**
3+
* phpDocumentor Example Tag Test
4+
*
5+
* PHP version 5.3
6+
*
7+
* @author Vasil Rangelov <[email protected]>
8+
* @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
9+
* @license http://www.opensource.org/licenses/mit-license.php MIT
10+
* @link http://phpdoc.org
11+
*/
12+
13+
namespace phpDocumentor\Reflection\DocBlock\Tag;
14+
15+
/**
16+
* Test class for \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag
17+
*
18+
* @author Vasil Rangelov <[email protected]>
19+
* @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
20+
* @license http://www.opensource.org/licenses/mit-license.php MIT
21+
* @link http://phpdoc.org
22+
*/
23+
class ExampleTagTest extends \PHPUnit_Framework_TestCase
24+
{
25+
/**
26+
* Test that the \phpDocumentor\Reflection\DocBlock\Tag\SourceTag can
27+
* understand the @source DocBlock.
28+
*
29+
* @param string $type
30+
* @param string $content
31+
* @param string $exContent
32+
* @param string $exStartingLine
33+
* @param string $exLineCount
34+
* @param string $exFilepath
35+
*
36+
* @covers \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag::__construct
37+
* @covers \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag::getFilePath
38+
* @dataProvider provideDataForConstuctor
39+
*
40+
* @return void
41+
*/
42+
public function testConstructorParesInputsIntoCorrectFields(
43+
$type,
44+
$content,
45+
$exContent,
46+
$exDescription,
47+
$exStartingLine,
48+
$exLineCount,
49+
$exFilePath
50+
) {
51+
$tag = new ExampleTag($type, $content);
52+
53+
$this->assertEquals($type, $tag->getName());
54+
$this->assertEquals($exContent, $tag->getContent());
55+
$this->assertEquals($exDescription, $tag->getDescription());
56+
$this->assertEquals($exStartingLine, $tag->getStartingLine());
57+
$this->assertEquals($exLineCount, $tag->getLineCount());
58+
$this->assertEquals($exFilePath, $tag->getFilePath());
59+
}
60+
61+
/**
62+
* Data provider for testConstructorParesInputsIntoCorrectFields
63+
*
64+
* @return array
65+
*/
66+
public function provideDataForConstuctor()
67+
{
68+
// $type, $content, $exContent, $exDescription, $exStartingLine, $exLineCount, $exFilePath
69+
return array(
70+
array(
71+
'example',
72+
'file.php',
73+
'file.php',
74+
'',
75+
1,
76+
null,
77+
'file.php'
78+
),
79+
array(
80+
'example',
81+
'Testing comments',
82+
'Testing comments',
83+
'comments',
84+
1,
85+
null,
86+
'Testing'
87+
),
88+
array(
89+
'example',
90+
'file.php 2 Testing',
91+
'file.php 2 Testing',
92+
'Testing',
93+
2,
94+
null,
95+
'file.php'
96+
),
97+
array(
98+
'example',
99+
'file.php 2 3 Testing comments',
100+
'file.php 2 3 Testing comments',
101+
'Testing comments',
102+
2,
103+
3,
104+
'file.php'
105+
),
106+
array(
107+
'example',
108+
'file.php 2 -1 Testing comments',
109+
'file.php 2 -1 Testing comments',
110+
'-1 Testing comments',
111+
2,
112+
null,
113+
'file.php'
114+
),
115+
array(
116+
'example',
117+
'file.php -1 1 Testing comments',
118+
'file.php -1 1 Testing comments',
119+
'-1 1 Testing comments',
120+
1,
121+
null,
122+
'file.php'
123+
),
124+
array(
125+
'example',
126+
'"file with spaces.php" Testing comments',
127+
'"file with spaces.php" Testing comments',
128+
'Testing comments',
129+
1,
130+
null,
131+
'file with spaces.php'
132+
),
133+
array(
134+
'example',
135+
'"file with spaces.php" 2 Testing comments',
136+
'"file with spaces.php" 2 Testing comments',
137+
'Testing comments',
138+
2,
139+
null,
140+
'file with spaces.php'
141+
),
142+
array(
143+
'example',
144+
'"file with spaces.php" 2 3 Testing comments',
145+
'"file with spaces.php" 2 3 Testing comments',
146+
'Testing comments',
147+
2,
148+
3,
149+
'file with spaces.php'
150+
),
151+
array(
152+
'example',
153+
'"file with spaces.php" 2 -3 Testing comments',
154+
'"file with spaces.php" 2 -3 Testing comments',
155+
'-3 Testing comments',
156+
2,
157+
null,
158+
'file with spaces.php'
159+
),
160+
array(
161+
'example',
162+
'"file with spaces.php" -2 3 Testing comments',
163+
'"file with spaces.php" -2 3 Testing comments',
164+
'-2 3 Testing comments',
165+
1,
166+
null,
167+
'file with spaces.php'
168+
),
169+
array(
170+
'example',
171+
'file%20with%20spaces.php Testing comments',
172+
'file%20with%20spaces.php Testing comments',
173+
'Testing comments',
174+
1,
175+
null,
176+
'file with spaces.php'
177+
),
178+
array(
179+
'example',
180+
'folder/file%20with%20spaces.php Testing comments',
181+
'folder/file%20with%20spaces.php Testing comments',
182+
'Testing comments',
183+
1,
184+
null,
185+
'folder/file with spaces.php'
186+
),
187+
array(
188+
'example',
189+
'http://example.com/file%20with%20spaces.php Testing comments',
190+
'http://example.com/file%20with%20spaces.php Testing comments',
191+
'Testing comments',
192+
1,
193+
null,
194+
'http://example.com/file%20with%20spaces.php'
195+
)
196+
);
197+
}
198+
}

0 commit comments

Comments
 (0)