Skip to content

Commit 3102ff8

Browse files
committed
Actualize readme
1 parent 218da90 commit 3102ff8

8 files changed

Lines changed: 769 additions & 430 deletions

File tree

docs/Writerside/tl.tree

Lines changed: 240 additions & 239 deletions
Large diffs are not rendered by default.

docs/Writerside/topics/phpdoc.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -156,10 +156,12 @@ fragments and the nested tags found among them.
156156
```
157157

158158
Only a handful of tags — [@see](see-tag.md), [@link](link-tag.md),
159-
[@internal](internal-tag.md) and [@inheritdoc](inheritdoc-tag.md) — are
160-
ever recognized this way. A `{@param}` written in running text, for instance, is never lifted
161-
out: `@param` only makes sense as a whole tag line, so the braces around it
162-
stay exactly as written, as plain text.
159+
[@internal](internal-tag.md), [@inheritdoc](inheritdoc-tag.md),
160+
[@example](example-tag.md) and [@source](source-tag.md) — are ever recognized
161+
this way. Whether a tag may be lifted out of running text is declared by its
162+
[placement](definitions.md#inline-tags); a `{@param}`, for instance, is never
163+
lifted out: `@param` is a block-only tag, so the braces around it stay exactly
164+
as written, as plain text.
163165

164166
### Tag
165167

docs/Writerside/topics/phpdoc/combinators.md

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<primary-label ref="phpdoc-component"/>
44
<show-structure for="chapter" depth="2"/>
55

6-
Every named building block a [tag's grammar](custom-tags.md) is assembled
6+
Every named building block a [tag's grammar](grammar.md) is assembled
77
from — a type, a variable, a URI, an email address — is a **combinator**:
88
a small object that knows how to read exactly one piece of syntax and
99
nothing else. `Spec::rule(TypeCombinator::NAME, 'type')` in
@@ -29,7 +29,7 @@ the value it read, or throws `NoMatchException` and leaves the cursor
2929
exactly where it found it. That second case matters: a combinator that
3030
partially consumes input before deciding it does not fit would corrupt
3131
whichever alternative the surrounding grammar tries next — see
32-
[`Spec::oneOf()`](custom-tags.md), which relies on being able to roll back
32+
[`Spec::oneOf()`](grammar.md), which relies on being able to roll back
3333
cleanly.
3434

3535
The `Cursor` itself offers the handful of reading operations most
@@ -43,7 +43,7 @@ whatever is left entirely.
4343

4444
## Built-in Combinators
4545

46-
Thirteen combinators cover every built-in tag's grammar between them:
46+
Fourteen combinators cover every built-in tag's grammar between them:
4747

4848
<table style="both">
4949
<tr>
@@ -52,9 +52,9 @@ Thirteen combinators cover every built-in tag's grammar between them:
5252
<td>Reads</td>
5353
</tr>
5454
<tr>
55-
<td><code>Access</code></td>
5655
<td><code>Visibility</code></td>
57-
<td>One of <code>public</code>, <code>protected</code> or <code>private</code>.</td>
56+
<td><code>Visibility</code></td>
57+
<td>Method or property visibility.</td>
5858
</tr>
5959
<tr>
6060
<td><code>AuthorName</code></td>
@@ -64,7 +64,7 @@ Thirteen combinators cover every built-in tag's grammar between them:
6464
<tr>
6565
<td><code>CallableType</code></td>
6666
<td><code>TypeReference</code></td>
67-
<td>A <a href="callable-types.md">type</a>, accepted only when it is a callable.</td>
67+
<td>A <a href="callable-types.md">TypeLang callable type</a>.</td>
6868
</tr>
6969
<tr>
7070
<td><code>Description</code></td>
@@ -116,6 +116,11 @@ Thirteen combinators cover every built-in tag's grammar between them:
116116
<td><code>string</code></td>
117117
<td>A <code>$name</code>, without the leading <code>$</code>.</td>
118118
</tr>
119+
<tr>
120+
<td><code>Version</code></td>
121+
<td><code>string</code></td>
122+
<td>A word beginning with a digit; <br />anything else is left for the description.</td>
123+
</tr>
119124
</table>
120125

121126
## Writing One of Your Own
@@ -153,7 +158,7 @@ Three habits keep a combinator well-behaved inside a larger grammar:
153158

154159
* **Fail before consuming.** Throw `NoMatchException` the moment the input
155160
is found not to fit, before reading anything that would belong to what
156-
comes next — a combinator that consumes first and validates afterwards
161+
comes next — a combinator that consumes first and validates afterward
157162
leaves the cursor somewhere a sibling alternative can no longer make sense
158163
of.
159164
* **Consume only your own syntax.** Whitespace meant to separate one grammar
@@ -165,5 +170,5 @@ Three habits keep a combinator well-behaved inside a larger grammar:
165170
surrounding `Spec::oneOf()` take over is safer than silently picking one.
166171

167172
Once written, a combinator with a `NAME` constant is used from a tag's
168-
`$spec` exactly like a built-in one — see
169-
[Declaring a Tag's Grammar](custom-tags.md).
173+
`$spec` exactly like a built-in one — see [Grammar](grammar.md). To make it
174+
available to the parser, register it on a [platform](platforms.md).

0 commit comments

Comments
 (0)