Skip to content

Commit 2b49b79

Browse files
committed
Allow see tag to url
The see tag allows Fqsen and uri's. But in the current implementation only Fqsen where allowed. This wrapps the uri and Fqsen in an uniform class to be able address them in the same way. Fixes #78
1 parent 51911ab commit 2b49b79

File tree

5 files changed

+158
-14
lines changed

5 files changed

+158
-14
lines changed

src/DocBlock/Tags/Reference/Fqsen.php

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
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-2017 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\Tags\Reference;
14+
15+
use phpDocumentor\Reflection\Fqsen as RealFqsen;
16+
17+
/**
18+
* Fqsen reference used by {@see phpDocumentor\Reflection\DocBlock\Tags\See}
19+
*/
20+
final class Fqsen implements Reference
21+
{
22+
/**
23+
* @var RealFqsen
24+
*/
25+
private $fqsen;
26+
27+
/**
28+
* Fqsen constructor.
29+
*/
30+
public function __construct(RealFqsen $fqsen)
31+
{
32+
$this->fqsen = $fqsen;
33+
}
34+
35+
/**
36+
* @return string string representation of the referenced fqsen
37+
*/
38+
public function __toString()
39+
{
40+
return (string)$this->fqsen;
41+
}
42+
}
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
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-2017 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\Tags\Reference;
14+
15+
/**
16+
* Interface for references in {@see phpDocumentor\Reflection\DocBlock\Tags\See}
17+
*/
18+
interface Reference
19+
{
20+
public function __toString();
21+
}

src/DocBlock/Tags/Reference/Url.php

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
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-2017 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\Tags\Reference;
14+
15+
use Webmozart\Assert\Assert;
16+
17+
/**
18+
* Url reference used by {@see phpDocumentor\Reflection\DocBlock\Tags\See}
19+
*/
20+
final class Url implements Reference
21+
{
22+
/**
23+
* @var string
24+
*/
25+
private $uri;
26+
27+
/**
28+
* Url constructor.
29+
*/
30+
public function __construct($uri)
31+
{
32+
Assert::stringNotEmpty($uri);
33+
$this->uri = $uri;
34+
}
35+
36+
public function __toString()
37+
{
38+
return $this->uri;
39+
}
40+
}

src/DocBlock/Tags/See.php

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
namespace phpDocumentor\Reflection\DocBlock\Tags;
1414

1515
use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
16+
use phpDocumentor\Reflection\DocBlock\Tags\Reference\Fqsen as FqsenRef;
17+
use phpDocumentor\Reflection\DocBlock\Tags\Reference\Reference;
18+
use phpDocumentor\Reflection\DocBlock\Tags\Reference\Url;
1619
use phpDocumentor\Reflection\Fqsen;
1720
use phpDocumentor\Reflection\FqsenResolver;
1821
use phpDocumentor\Reflection\Types\Context as TypeContext;
@@ -26,16 +29,16 @@ class See extends BaseTag implements Factory\StaticMethod
2629
{
2730
protected $name = 'see';
2831

29-
/** @var Fqsen */
32+
/** @var Reference */
3033
protected $refers = null;
3134

3235
/**
3336
* Initializes this tag.
3437
*
35-
* @param Fqsen $refers
38+
* @param Reference $refers
3639
* @param Description $description
3740
*/
38-
public function __construct(Fqsen $refers, Description $description = null)
41+
public function __construct(Reference $refers, Description $description = null)
3942
{
4043
$this->refers = $refers;
4144
$this->description = $description;
@@ -56,13 +59,18 @@ public static function create(
5659
$parts = preg_split('/\s+/Su', $body, 2);
5760
$description = isset($parts[1]) ? $descriptionFactory->create($parts[1], $context) : null;
5861

59-
return new static($resolver->resolve($parts[0], $context), $description);
62+
// https://tools.ietf.org/html/rfc2396#section-3
63+
if (preg_match('/\w:\/\/\w/i', $parts[0])) {
64+
return new static(new Url($parts[0]), $description);
65+
}
66+
67+
return new static(new FqsenRef($resolver->resolve($parts[0], $context)), $description);
6068
}
6169

6270
/**
63-
* Returns the structural element this tag refers to.
71+
* Returns the ref of this tag.
6472
*
65-
* @return Fqsen
73+
* @return Reference
6674
*/
6775
public function getReference()
6876
{

tests/unit/DocBlock/Tags/SeeTest.php

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
use Mockery as m;
1616
use phpDocumentor\Reflection\DocBlock\Description;
1717
use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
18+
use phpDocumentor\Reflection\DocBlock\Tags\Reference\Fqsen as FqsenRef;
19+
use phpDocumentor\Reflection\DocBlock\Tags\Reference\Url as UrlRef;
1820
use phpDocumentor\Reflection\Fqsen;
1921
use phpDocumentor\Reflection\FqsenResolver;
2022
use phpDocumentor\Reflection\Types\Context;
@@ -32,7 +34,7 @@ class SeeTest extends \PHPUnit_Framework_TestCase
3234
*/
3335
public function testIfCorrectTagNameIsReturned()
3436
{
35-
$fixture = new See(new Fqsen('\DateTime'), new Description('Description'));
37+
$fixture = new See(new FqsenRef(new Fqsen('\DateTime')), new Description('Description'));
3638

3739
$this->assertSame('see', $fixture->getName());
3840
}
@@ -47,7 +49,7 @@ public function testIfCorrectTagNameIsReturned()
4749
*/
4850
public function testIfTagCanBeRenderedUsingDefaultFormatter()
4951
{
50-
$fixture = new See(new Fqsen('\DateTime'), new Description('Description'));
52+
$fixture = new See(new FqsenRef(new Fqsen('\DateTime')), new Description('Description'));
5153

5254
$this->assertSame('@see \DateTime Description', $fixture->render());
5355
}
@@ -59,7 +61,7 @@ public function testIfTagCanBeRenderedUsingDefaultFormatter()
5961
*/
6062
public function testIfTagCanBeRenderedUsingSpecificFormatter()
6163
{
62-
$fixture = new See(new Fqsen('\DateTime'), new Description('Description'));
64+
$fixture = new See(new FqsenRef(new Fqsen('\DateTime')), new Description('Description'));
6365

6466
$formatter = m::mock(Formatter::class);
6567
$formatter->shouldReceive('format')->with($fixture)->andReturn('Rendered output');
@@ -73,7 +75,7 @@ public function testIfTagCanBeRenderedUsingSpecificFormatter()
7375
*/
7476
public function testHasReferenceToFqsen()
7577
{
76-
$expected = new Fqsen('\DateTime');
78+
$expected = new FqsenRef(new Fqsen('\DateTime'));
7779

7880
$fixture = new See($expected);
7981

@@ -89,7 +91,7 @@ public function testHasDescription()
8991
{
9092
$expected = new Description('Description');
9193

92-
$fixture = new See(new Fqsen('\DateTime'), $expected);
94+
$fixture = new See(new FqsenRef(new Fqsen('\DateTime')), $expected);
9395

9496
$this->assertSame($expected, $fixture->getDescription());
9597
}
@@ -101,9 +103,9 @@ public function testHasDescription()
101103
*/
102104
public function testStringRepresentationIsReturned()
103105
{
104-
$fixture = new See(new Fqsen('\DateTime'), new Description('Description'));
106+
$fixture = new See(new FqsenRef(new Fqsen('\DateTime::format()')), new Description('Description'));
105107

106-
$this->assertSame('\DateTime Description', (string)$fixture);
108+
$this->assertSame('\DateTime::format() Description', (string)$fixture);
107109
}
108110

109111
/**
@@ -131,7 +133,38 @@ public function testFactoryMethod()
131133
$fixture = See::create('DateTime My Description', $resolver, $descriptionFactory, $context);
132134

133135
$this->assertSame('\DateTime My Description', (string)$fixture);
134-
$this->assertSame($fqsen, $fixture->getReference());
136+
$this->assertInstanceOf(FqsenRef::class, $fixture->getReference());
137+
$this->assertSame((string)$fqsen, (string)$fixture->getReference());
138+
$this->assertSame($description, $fixture->getDescription());
139+
}
140+
141+
/**
142+
* @covers ::create
143+
* @uses \phpDocumentor\Reflection\DocBlock\Tags\See::<public>
144+
* @uses \phpDocumentor\Reflection\DocBlock\DescriptionFactory
145+
* @uses \phpDocumentor\Reflection\FqsenResolver
146+
* @uses \phpDocumentor\Reflection\DocBlock\Description
147+
* @uses \phpDocumentor\Reflection\DocBlock\Tags\Reference\Url
148+
* @uses \phpDocumentor\Reflection\Types\Context
149+
*/
150+
public function testFactoryMethodWithUrl()
151+
{
152+
$descriptionFactory = m::mock(DescriptionFactory::class);
153+
$resolver = m::mock(FqsenResolver::class);
154+
$context = new Context('');
155+
156+
$description = new Description('My Description');
157+
158+
$descriptionFactory
159+
->shouldReceive('create')->with('My Description', $context)->andReturn($description);
160+
161+
$resolver->shouldNotReceive('resolve');
162+
163+
$fixture = See::create('https://test.org My Description', $resolver, $descriptionFactory, $context);
164+
165+
$this->assertSame('https://test.org My Description', (string)$fixture);
166+
$this->assertInstanceOf(UrlRef::class, $fixture->getReference());
167+
$this->assertSame('https://test.org', (string)$fixture->getReference());
135168
$this->assertSame($description, $fixture->getDescription());
136169
}
137170

0 commit comments

Comments
 (0)