Skip to content

Commit c55b2c5

Browse files
author
Kirill Nesmeyanov
committed
Remove unused interfaces
1 parent 8e3c8d7 commit c55b2c5

15 files changed

+204
-87
lines changed

‎README.md‎

Lines changed: 147 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,151 @@
1616

1717
The PHP reference implementation for Type Language PhpDoc Parser.
1818

19-
## Resources
19+
Read [documentation pages](https://phpdoc.io) for more information.
2020

21-
- [Documentation](https://phpdoc.io)
21+
## Installation
22+
23+
Type Language PHPDoc Parser is available as Composer repository and can
24+
be installed using the following command in a root of your project:
25+
26+
```sh
27+
$ composer require type-lang/phpdoc-parser
28+
```
29+
30+
## Quick Start
31+
32+
```php
33+
$parser = new \TypeLang\PHPDoc\Parser();
34+
$result = $parser->parse(<<<'PHPDOC'
35+
/**
36+
* Example description {@see some} and blah-blah-blah.
37+
*
38+
* @Example\Annotation("foo")
39+
* @return array<non-empty-string, TypeStatement>
40+
* @throws \Throwable
41+
*/
42+
PHPDOC);
43+
44+
var_dump($result);
45+
```
46+
47+
**Expected Output:**
48+
```
49+
TypeLang\PHPDoc\DocBlock {
50+
-description: TypeLang\PHPDoc\Tag\Description\Description {
51+
-template: "Example description %1$s and blah-blah-blah."
52+
-tags: array:1 [
53+
0 => TypeLang\PHPDoc\Tag\Tag {
54+
#description: TypeLang\PHPDoc\Tag\Description\Description {
55+
-template: "some"
56+
-tags: []
57+
}
58+
#name: "see"
59+
}
60+
]
61+
}
62+
-tags: array:3 [
63+
0 => TypeLang\PHPDoc\Tag\Tag {
64+
#description: TypeLang\PHPDoc\Tag\Description\Description {
65+
-template: "("foo")"
66+
-tags: []
67+
}
68+
#name: "Example\Annotation"
69+
}
70+
1 => TypeLang\PHPDoc\Tag\Tag {
71+
#description: TypeLang\PHPDoc\Tag\Description\Description {
72+
-template: "array<non-empty-string, TypeStatement>"
73+
-tags: []
74+
}
75+
#name: "return"
76+
}
77+
2 => TypeLang\PHPDoc\Tag\Tag {
78+
#description: TypeLang\PHPDoc\Tag\Description\Description {
79+
-template: "\Throwable"
80+
-tags: []
81+
}
82+
#name: "throws"
83+
}
84+
]
85+
}
86+
```
87+
88+
### Structural Elements
89+
90+
**DocBlock**
91+
92+
DocBlock is a representation of the comment object.
93+
94+
```php
95+
/** |
96+
* Hello world | ← DocBlock's description.
97+
* |
98+
* @param int $example | ← DocBlock's tag #1.
99+
* @throws \Throwable Description | ← DocBlock's tag #2.
100+
*/ |
101+
```
102+
103+
- `getDescription()` ― Provides a `Description` object.
104+
- `getTags()` ― Provides a list of `Tag` objects.
105+
106+
```php
107+
/** @template-implements \Traversable<array-key, Tag> */
108+
class DocBlock implements \Traversable
109+
{
110+
public function getDescription(): Description;
111+
112+
/** @return list<Tag> */
113+
public function getTags(): array;
114+
}
115+
```
116+
117+
**Description**
118+
119+
Description is a representation of the description object which may contain
120+
other tags.
121+
122+
```php
123+
/**
124+
↓↓↓↓↓↓↓↓↓↓↓ | ← This is a nested tag of the description.
125+
* Hello world {@see some} and blah-blah-blah. |
126+
↑↑↑↑↑↑↑↑↑↑↑ ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ | ← This is part of the template.
127+
*/
128+
```
129+
130+
- `getTemplate()` ― Provides a sprintf-formatted template string of the description.
131+
- `getTags()` ― Provides a list of `Tag` objects.
132+
133+
```php
134+
/** @template-implements \Traversable<array-key, Tag> */
135+
class Description implements \Traversable, \Stringable
136+
{
137+
public function getTemplate(): string;
138+
139+
/** @return list<Tag> */
140+
public function getTags(): array;
141+
}
142+
```
143+
144+
**Tag**
145+
146+
A Tag represents a name (ID) and its contents.
147+
148+
```php
149+
/**
150+
↓↓↓↓↓↓ | ← This is a tag name.
151+
* @throws \Throwable An error occurred. |
152+
↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ | ← This is tag description.
153+
*/
154+
```
155+
156+
- `getName()` ― Provides a tag's name (ID).
157+
- `getDescription()` ― Provides an optional description of the tag.
158+
159+
```php
160+
class Tag implements \Stringable
161+
{
162+
public function getName(): string;
163+
164+
public function getDescription(): ?Description;
165+
}
166+
```

‎src/DocBlock.php‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,30 @@
44

55
namespace TypeLang\PHPDoc;
66

7-
use TypeLang\PHPDoc\Tag\Description\Description;
8-
use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
9-
use TypeLang\PHPDoc\Tag\TagInterface;
7+
use TypeLang\PHPDoc\Tag\Description;
8+
use TypeLang\PHPDoc\Tag\Tag;
109
use TypeLang\PHPDoc\Tag\TagProvider;
1110
use TypeLang\PHPDoc\Tag\TagProviderInterface;
1211

1312
/**
14-
* @template-implements \IteratorAggregate<array-key, TagInterface>
13+
* @template-implements \IteratorAggregate<array-key, Tag>
1514
*/
1615
final class DocBlock implements TagProviderInterface, \IteratorAggregate
1716
{
1817
use TagProvider;
1918

2019
/**
21-
* @param iterable<array-key, TagInterface> $tags
20+
* @param iterable<array-key, Tag> $tags
2221
*/
2322
public function __construct(
24-
private readonly DescriptionInterface $description = new Description(),
23+
private readonly Description $description = new Description(),
2524
iterable $tags = [],
2625
) {
2726
$this->bootTagProvider($tags);
2827
}
28+
29+
public function getDescription(): Description
30+
{
31+
return $this->description;
32+
}
2933
}

‎src/Parser/Comment/CommentParserInterface.php‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,6 @@
77
/**
88
* This interface is responsible for reading significant
99
* sections of the DocBlock comment.
10-
*
11-
* @internal This is an internal library interface, please do not use it in your code.
12-
* @psalm-internal TypeLang\PHPDoc
1310
*/
1411
interface CommentParserInterface
1512
{

‎src/Parser/Comment/LexerAwareCommentParser.php‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,6 @@
1717
/**
1818
* This class is responsible for reading significant
1919
* sections of the DocBlock comment.
20-
*
21-
* @internal This is an internal library class, please do not use it in your code.
22-
* @psalm-internal TypeLang\PHPDoc
2320
*/
2421
final class LexerAwareCommentParser implements CommentParserInterface
2522
{

‎src/Parser/Description/DescriptionParser.php‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,11 @@
55
namespace TypeLang\PHPDoc\Parser\Description;
66

77
use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
8-
use TypeLang\PHPDoc\Tag\Description\Description;
9-
use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
8+
use TypeLang\PHPDoc\Tag\Description;
109

1110
abstract class DescriptionParser implements DescriptionParserInterface
1211
{
13-
public function parse(string $description, TagParserInterface $parser = null): DescriptionInterface
12+
public function parse(string $description, TagParserInterface $parser = null): Description
1413
{
1514
if ($parser === null || $description === '') {
1615
return new Description($description);
@@ -19,7 +18,7 @@ public function parse(string $description, TagParserInterface $parser = null): D
1918
return $this->doParseDescription($description, $parser);
2019
}
2120

22-
private function doParseDescription(string $description, TagParserInterface $parser): DescriptionInterface
21+
private function doParseDescription(string $description, TagParserInterface $parser): Description
2322
{
2423
$tags = [];
2524
$tagIdentifier = 0;

‎src/Parser/Description/DescriptionParserInterface.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
namespace TypeLang\PHPDoc\Parser\Description;
66

77
use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
8-
use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
8+
use TypeLang\PHPDoc\Tag\Description;
99

1010
interface DescriptionParserInterface
1111
{
@@ -26,5 +26,5 @@ interface DescriptionParserInterface
2626
* // }
2727
* ```
2828
*/
29-
public function parse(string $description, TagParserInterface $parser = null): DescriptionInterface;
29+
public function parse(string $description, TagParserInterface $parser = null): Description;
3030
}

‎src/Parser/SourceMap.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
namespace TypeLang\PHPDoc\Parser;
66

7+
/**
8+
* @internal This is an internal library class, please do not use it in your code.
9+
* @psalm-internal TypeLang\PHPDoc
10+
*/
711
final class SourceMap
812
{
913
/**

‎src/Parser/Tag/TagParser.php‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
use TypeLang\PHPDoc\Exception\InvalidTagNameException;
88
use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
99
use TypeLang\PHPDoc\Tag\Tag;
10-
use TypeLang\PHPDoc\Tag\TagInterface;
1110

1211
final class TagParser implements TagParserInterface
1312
{
@@ -73,7 +72,7 @@ private function getTagParts(string $content): array
7372
/**
7473
* @throws InvalidTagNameException
7574
*/
76-
public function parse(string $tag, DescriptionParserInterface $parser = null): TagInterface
75+
public function parse(string $tag, DescriptionParserInterface $parser = null): Tag
7776
{
7877
// Tag name like ["var", "example"] extracted from "@var example"
7978
[$name, $content] = $this->getTagParts($tag);

‎src/Parser/Tag/TagParserInterface.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
namespace TypeLang\PHPDoc\Parser\Tag;
66

77
use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
8-
use TypeLang\PHPDoc\Tag\TagInterface;
8+
use TypeLang\PHPDoc\Tag\Tag;
99

1010
interface TagParserInterface
1111
{
@@ -24,5 +24,5 @@ interface TagParserInterface
2424
* // }
2525
* ```
2626
*/
27-
public function parse(string $tag, DescriptionParserInterface $parser = null): TagInterface;
27+
public function parse(string $tag, DescriptionParserInterface $parser = null): Tag;
2828
}

‎src/Tag/Description/Description.php‎ renamed to ‎src/Tag/Description.php‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,26 @@
22

33
declare(strict_types=1);
44

5-
namespace TypeLang\PHPDoc\Tag\Description;
6-
7-
use TypeLang\PHPDoc\Tag\TagInterface;
8-
use TypeLang\PHPDoc\Tag\TagProvider;
9-
use TypeLang\PHPDoc\Tag\TagProviderInterface;
5+
namespace TypeLang\PHPDoc\Tag;
106

117
/**
12-
* @template-implements \IteratorAggregate<array-key, TagInterface>
8+
* @template-implements \IteratorAggregate<array-key, Tag>
139
*/
14-
final class Description implements DescriptionInterface, TagProviderInterface, \IteratorAggregate
10+
class Description implements \Stringable, TagProviderInterface, \IteratorAggregate
1511
{
1612
use TagProvider;
1713

14+
private readonly string $template;
15+
1816
/**
19-
* @param iterable<array-key, TagInterface> $tags
17+
* @param iterable<array-key, Tag> $tags
2018
*/
2119
public function __construct(
22-
private readonly string|\Stringable $template = '',
20+
string|\Stringable $template = '',
2321
iterable $tags = [],
2422
) {
23+
$this->template = (string) $template;
24+
2525
$this->bootTagProvider($tags);
2626
}
2727

@@ -49,7 +49,7 @@ public static function fromStringOrNull(string|\Stringable|null $description): ?
4949
* @api
5050
* @psalm-immutable
5151
*/
52-
public function getTemplate(): string|\Stringable
52+
public function getTemplate(): string
5353
{
5454
return $this->template;
5555
}

0 commit comments

Comments
 (0)