Skip to content

Commit 13203e3

Browse files
SerafimArtsSerafimArts
committed
Add "@link" and "@see" tags support
1 parent 2c07189 commit 13203e3

35 files changed

+735
-63
lines changed

Diff for: ‎composer.json

+1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
},
1111
"require": {
1212
"php": "^8.1",
13+
"league/uri": "^7.5",
1314
"type-lang/parser": "^1.5"
1415
},
1516
"replace": {

Diff for: ‎src/DocBlock/Tag/LinkTag/LinkTag.php

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\LinkTag;
6+
7+
use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\UriReference;
8+
use TypeLang\PHPDoc\DocBlock\Tag\Tag;
9+
10+
/**
11+
* The "`@link`" tag can be used to define a relation, or link, between
12+
* the symbol, or part of the long description when used inline, to a URI.
13+
*
14+
* The URI MUST be complete and well-formed as specified in RFC2396.
15+
*
16+
* The "`@link`" tag MAY have a description appended to indicate the type of
17+
* relation defined by this occurrence.
18+
*
19+
* ```
20+
*
21+
* * @link [URI] [<description>]
22+
* ```
23+
* @link https://www.ietf.org/rfc/rfc2396.txt RFC2396
24+
*/
25+
final class LinkTag extends Tag
26+
{
27+
public function __construct(
28+
string $name,
29+
public readonly UriReference $uri,
30+
\Stringable|string|null $description = null,
31+
) {
32+
parent::__construct($name, $description);
33+
}
34+
}

Diff for: ‎src/DocBlock/Tag/LinkTag/LinkTagFactory.php

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\LinkTag;
6+
7+
use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
8+
use TypeLang\PHPDoc\Parser\Content\Stream;
9+
use TypeLang\PHPDoc\Parser\Content\UriReferenceReader;
10+
use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
11+
12+
/**
13+
* This class is responsible for creating "`@link`" tags.
14+
*
15+
* See {@see LinkTag} for details about this tag.
16+
*/
17+
final class LinkTagFactory implements TagFactoryInterface
18+
{
19+
public function create(string $tag, string $content, DescriptionParserInterface $descriptions): LinkTag
20+
{
21+
$stream = new Stream($tag, $content);
22+
23+
return new LinkTag(
24+
name: $tag,
25+
uri: $stream->apply(new UriReferenceReader()),
26+
description: $stream->toOptionalDescription($descriptions),
27+
);
28+
}
29+
}

Diff for: ‎src/DocBlock/Tag/MethodTag/MethodTag.php

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
* with a class or interface.
3737
*
3838
* ```
39+
*
3940
* * @method [static] <CallableType> [<description>]
4041
* * @method [static] <ReturnType> <CallableType> [<description>]
4142
* * @method [static] <CallableType>: <ReturnType> [<description>]

Diff for: ‎src/DocBlock/Tag/SeeTag/SeeTag.php

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\SeeTag;
6+
7+
use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ReferenceInterface;
8+
use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\SymbolReference;
9+
use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\UriReference;
10+
use TypeLang\PHPDoc\DocBlock\Tag\Tag;
11+
12+
/**
13+
* The "`@see`" tag can be used to define a {@see SymbolReference symbol} or
14+
* to an {@see UriReference external URI}.
15+
*
16+
* When defining a reference to other symbols, you can refer to a specific
17+
* element by appending a double colon and providing the name of that element
18+
* (also called the 'Fully Qualified Name' or _FQN_).
19+
*
20+
* A URI MUST be complete and well-formed as specified in RFC 2396.
21+
*
22+
* The "`@see"` tag SHOULD have a description to provide additional information
23+
* regarding the relationship between the element and its target.
24+
*
25+
* The "`@see`" tag cannot refer to a namespace element.
26+
*
27+
* ```
28+
*
29+
* * @see [URI | FQN] [<description>]
30+
* ```
31+
*
32+
* @link https://www.ietf.org/rfc/rfc2396.txt RFC2396
33+
*/
34+
final class SeeTag extends Tag
35+
{
36+
public function __construct(
37+
string $name,
38+
public readonly ReferenceInterface $ref,
39+
\Stringable|string|null $description = null,
40+
) {
41+
parent::__construct($name, $description);
42+
}
43+
}

Diff for: ‎src/DocBlock/Tag/SeeTag/SeeTagFactory.php

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\SeeTag;
6+
7+
use TypeLang\Parser\Parser as TypesParser;
8+
use TypeLang\Parser\ParserInterface as TypesParserInterface;
9+
use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
10+
use TypeLang\PHPDoc\Parser\Content\Stream;
11+
use TypeLang\PHPDoc\Parser\Content\SymbolReferenceReader;
12+
use TypeLang\PHPDoc\Parser\Content\UriReferenceReader;
13+
use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
14+
15+
/**
16+
* This class is responsible for creating "`@see`" tags.
17+
*
18+
* See {@see SeeTag} for details about this tag.
19+
*/
20+
final class SeeTagFactory implements TagFactoryInterface
21+
{
22+
public function __construct(
23+
private readonly TypesParserInterface $parser = new TypesParser(tolerant: true),
24+
) {}
25+
26+
public function create(string $tag, string $content, DescriptionParserInterface $descriptions): SeeTag
27+
{
28+
$stream = new Stream($tag, $content);
29+
30+
try {
31+
$reference = $stream->apply(new UriReferenceReader());
32+
} catch (\Throwable) {
33+
$reference = $stream->apply(new SymbolReferenceReader($this->parser));
34+
}
35+
36+
return new SeeTag(
37+
name: $tag,
38+
ref: $reference,
39+
description: $stream->toOptionalDescription($descriptions),
40+
);
41+
}
42+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/ClassConstantSymbolReference.php

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Name;
8+
9+
/**
10+
* Related to any internal class property reference
11+
*/
12+
final class ClassConstantSymbolReference extends ClassSymbolReference
13+
{
14+
public function __construct(
15+
Name $class,
16+
/**
17+
* @var non-empty-string
18+
*/
19+
public readonly string $constant,
20+
) {
21+
parent::__construct($class);
22+
}
23+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/ClassMethodSymbolReference.php

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Name;
8+
9+
/**
10+
* Related to any internal class property reference
11+
*/
12+
final class ClassMethodSymbolReference extends ClassSymbolReference
13+
{
14+
public function __construct(
15+
Name $class,
16+
/**
17+
* @var non-empty-string
18+
*/
19+
public readonly string $method,
20+
) {
21+
parent::__construct($class);
22+
}
23+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/ClassPropertySymbolReference.php

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Name;
8+
9+
/**
10+
* Related to any internal class property reference
11+
*/
12+
final class ClassPropertySymbolReference extends ClassSymbolReference
13+
{
14+
public function __construct(
15+
Name $class,
16+
/**
17+
* @var non-empty-string
18+
*/
19+
public readonly string $property,
20+
) {
21+
parent::__construct($class);
22+
}
23+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/ClassSymbolReference.php

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Name;
8+
9+
/**
10+
* Related to any internal class reference
11+
*/
12+
abstract class ClassSymbolReference extends SymbolReference
13+
{
14+
public function __construct(
15+
public readonly Name $class,
16+
) {}
17+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/FunctionReference.php

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Name;
8+
9+
/**
10+
* Related to internal function reference
11+
*/
12+
final class FunctionReference extends SymbolReference
13+
{
14+
public function __construct(
15+
public readonly Name $function,
16+
) {}
17+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/ReferenceInterface.php

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
/**
8+
* Represents reference to the external or internal symbol
9+
*/
10+
interface ReferenceInterface {}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/SymbolReference.php

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
/**
8+
* Related to any internal reference
9+
*/
10+
abstract class SymbolReference implements ReferenceInterface {}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/TypeSymbolReference.php

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Stmt\TypeStatement;
8+
9+
/**
10+
* Related to internal type reference
11+
*/
12+
final class TypeSymbolReference extends SymbolReference
13+
{
14+
public function __construct(
15+
public readonly TypeStatement $type,
16+
) {}
17+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/UriReference.php

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use League\Uri\Contracts\UriInterface;
8+
9+
/**
10+
* Related to external URI reference
11+
*/
12+
final class UriReference implements ReferenceInterface
13+
{
14+
public function __construct(
15+
public readonly UriInterface $uri,
16+
) {}
17+
}

Diff for: ‎src/DocBlock/Tag/Shared/Reference/VariableReference.php

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
6+
7+
use TypeLang\Parser\Node\Literal\VariableLiteralNode;
8+
9+
/**
10+
* Related to local variable reference
11+
*/
12+
final class VariableReference extends SymbolReference
13+
{
14+
public function __construct(
15+
public readonly VariableLiteralNode $variable,
16+
) {}
17+
}

0 commit comments

Comments
 (0)