Skip to content

Commit

Permalink
Improve documentation pages and UI
Browse files Browse the repository at this point in the history
  • Loading branch information
@SerafimArts
SerafimArts committed Apr 7, 2024
1 parent 842e441 commit 9957882
Show file tree
Hide file tree
Showing 8 changed files with 231 additions and 62 deletions.
10 changes: 8 additions & 2 deletions Writerside/cfg/buildprofiles.xml
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<sitemap priority="0.35" change-frequency="monthly"/>

<variables>
<primary-color>iris</primary-color>
<primary-color>blueberry</primary-color>
<color-preset>vivid</color-preset>
<custom-favicons>logo.svg</custom-favicons>
<header-logo>logo.svg</header-logo>
<product-web-url>https://typelang.dev</product-web-url>
<noindex-content>false</noindex-content>
<offline-docs>true</offline-docs>

<feedback-url>https://github.com/php-type-language/docs/issues</feedback-url>
<web-root>/</web-root>
Expand All @@ -22,7 +26,9 @@
</variables>

<footer>
<link href="https://github.com/php-type-language" />
<social href="https://github.com/php-type-language" type="blog">GitHub</social>
<link href="https://github.com/php-type-language/parser/issues">Issue tracker</link>
<link href="https://github.com/php-type-language/parser/pulls">Submit request</link>
<copyright>PHP TypeLang</copyright>
</footer>
</buildprofiles>
2 changes: 2 additions & 0 deletions Writerside/cfg/glossary.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,6 @@
<!DOCTYPE terms SYSTEM "https://resources.jetbrains.com/writerside/1.0/glossary.dtd">
<terms>
<term name="FQN">Fully Qualified Name</term>
<term name="Identifier">A sequence that begins with a letter and contains letters,
numbers, underscores, and dashes.</term>
</terms>
8 changes: 4 additions & 4 deletions Writerside/tl.tree
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,14 @@
SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">

<instance-profile id="tl"
name="TypeLang"
name="PHP TypeLang"
status="eap"
is-library="true"
start-page="overview.topic">

<toc-element topic="overview.topic">
<toc-element topic="overview.topic" />

<toc-element topic="language.md" toc-title="Syntax">
<toc-element topic="basic-types.md"/>
<toc-element topic="logical-types.md"/>
<toc-element topic="generic-types.md"/>
Expand All @@ -17,8 +19,6 @@
<toc-element topic="callables.md"/>
</toc-element>

<toc-element topic="language.md" />

<toc-element topic="parser.md">
<toc-element topic="visitors.md"/>
</toc-element>
Expand Down
42 changes: 21 additions & 21 deletions Writerside/topics/language/language.md → Writerside/topics/language.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,24 +91,24 @@ Below is a list of grammar of shaped types.

Below is a list of grammar of callable (function) types.

| Code Example | TypeLang | Psalm | PHPStan |
|-----------------------------------------------------------------------|-------------------|----------------------------------------------------|-------------|
| Simple Func `callable()` | ✔️ | ✔️ | ✔️ |
| Typed Func `callable(): mixed` | ✔️ | ✔️ | ✔️ |
| Func Args `callable(T)` | ✔️ | ✔️ | ✔️ |
| Optional Arg `callable(T=)` | ✔️ | ✔️ | ✔️ |
| Named Arg `callable(T $name)` | ✔️ | ✔️ | ✔️ |
| Optional Named Arg `callable(T $name=)` | ✔️ | [❌ Internal Error](https://psalm.dev/r/9ae58ed797) | ✔️ |
| Suffixed Variadic Arg `callable(T...)` | ✔️ | ✔️ | ✔️ |
| Prefixed Variadic Arg `callable(...T)` | ✔️ | ✔️ | ✔️ |
| Prefixed + Suffixed Variadic Named Arg `callable(...T ...$name)` | ✔️ Syntax Error | [❌ Internal Error](https://psalm.dev/r/4a6476fff6) | ❌ No Error |
| Optional Variadic Arg `callable(...T=)` | ✔️ Semantic Error | ✔️ Semantic Error | ✔️ No Error |
| Suffixed Variadic Named Arg `callable(T ...$arg)` | ✔️ | ✔️ | ✔️ |
| Prefixed Variadic Named Arg `callable(...T $arg)` | ✔️ | [❌ Internal Error](https://psalm.dev/r/2dac434b3f) | ✔️ |
| Reference Arg `callable(T&)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/bb604c4219) | ✔️ |
| Optional Reference Arg `callable(T&=)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/fc3041a846) | ✔️ |
| Optional Reference Named Arg `callable(T &$name=)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/14dcf8634f) | ✔️ |
| Reference Named Variadic Arg `callable(T &...$name)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/7a64356034) | ✔️ |
| Reference Named Prefix Variadic Arg `callable(...T &$name)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/bf7dcbc9b4) | ✔️ |
| Optional Reference Named Variadic Arg `callable(T &...$name=)` | ✔️ Semantic Error | ✔️ Semantic Error | ❌ No Error |
| Optional Reference Named Prefix Variadic Arg `callable(...T &$name=)` | ✔️ Semantic Error | ✔️ Semantic Error | ❌ No Error |
| Code Example | TypeLang | Psalm | PHPStan |
|-----------------------------------------------------------------------|-------------------|----------------------------------------------------|------------|
| Simple Func `callable()` | ✔️ | ✔️ | ✔️ |
| Typed Func `callable(): mixed` | ✔️ | ✔️ | ✔️ |
| Func Args `callable(T)` | ✔️ | ✔️ | ✔️ |
| Optional Arg `callable(T=)` | ✔️ | ✔️ | ✔️ |
| Named Arg `callable(T $name)` | ✔️ | ✔️ | ✔️ |
| Optional Named Arg `callable(T $name=)` | ✔️ | [❌ Internal Error](https://psalm.dev/r/9ae58ed797) | ✔️ |
| Suffixed Variadic Arg `callable(T...)` | ✔️ | ✔️ | ✔️ |
| Prefixed Variadic Arg `callable(...T)` | ✔️ | ✔️ | ✔️ |
| Prefixed + Suffixed Variadic Named Arg `callable(...T ...$name)` | ✔️ Syntax Error | [❌ Internal Error](https://psalm.dev/r/4a6476fff6) | ❌ No Error |
| Optional Variadic Arg `callable(...T=)` | ✔️ Semantic Error | ✔️ Semantic Error | ❌ No Error |
| Suffixed Variadic Named Arg `callable(T ...$arg)` | ✔️ | ✔️ | ✔️ |
| Prefixed Variadic Named Arg `callable(...T $arg)` | ✔️ | [❌ Internal Error](https://psalm.dev/r/2dac434b3f) | ✔️ |
| Reference Arg `callable(T&)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/bb604c4219) | ✔️ |
| Optional Reference Arg `callable(T&=)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/fc3041a846) | ✔️ |
| Optional Reference Named Arg `callable(T &$name=)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/14dcf8634f) | ✔️ |
| Reference Named Variadic Arg `callable(T &...$name)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/7a64356034) | ✔️ |
| Reference Named Prefix Variadic Arg `callable(...T &$name)` | ✔️ | [❌ Not Supported](https://psalm.dev/r/bf7dcbc9b4) | ✔️ |
| Optional Reference Named Variadic Arg `callable(T &...$name=)` | ✔️ Semantic Error | ✔️ Semantic Error | ❌ No Error |
| Optional Reference Named Prefix Variadic Arg `callable(...T &$name=)` | ✔️ Semantic Error | ✔️ Semantic Error | ❌ No Error |
98 changes: 79 additions & 19 deletions Writerside/topics/language/basic-types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ characters `[a-zA-Z\x80-\xff]` (any letter) and `_` (underscore) and can contain
within the limit `[a-zA-Z0-9\x80-\xff]` (any letter), as well as the characters `_` (underscore) and `-` (dash).

> For our purposes here, a **letter** is `a-z`, `A-Z`, and the bytes from 128 through 255 (`0x80-0xff`).
{style="note"}
In this case, the only difference from [the PHP grammar](https://www.php.net/manual/en/language.variables.basics.php)
is that a **dash** (`-`) symbol is allowed in the middle of the name.
Expand All @@ -16,39 +15,100 @@ PHP literals, so their use as a custom type name is **unacceptable**.
<tabs>
<tab title="examples">

* ✔️ **example**
* ✔️ **ExampleTypeName**
* ✔️ **example-type** — Dash (`-`) char is allowed.
* ✔️ **example-42** — Digits is allowed.
* ✔️ **true-type** — The reserved keyword (`true`) is allowed as part of the full name.
> Example of a simple <tooltip term="Identifier">Identifier</tooltip>.
> ```typescript
> ExampleTypeName
> ```
> {style="note"}
> Dashes (`-`) in <tooltip term="Identifier">Identifier</tooltip>
> are also acceptable.
> ```typescript
> example-type
> ```
> {style="note"}
> The reserved keyword (`true`) is allowed as part of the <tooltip
> term="Identifier">Identifier</tooltip>.
> ```typescript
> true-type
> ```
> {style="note"}
</tab>
<tab title="counterexamples">
* ❌ **true** — Reserved name.
* ❌ **TRUE** — Reserved name (case-insensitive).
* ❌ **42type** — Starts with a number.
* ❌ **-type** — Starts with a dash symbol.
> The standalone keywords (`true`) is NOT available as an <tooltip
> term="Identifier">Identifier</tooltip> regardless of case and is
> parsed as a literal value rather than an <tooltip
> term="Identifier">Identifier</tooltip>.
> ```typescript
> TrUe
>
> // TypeLang\Parser\Node\Literal\BoolLiteralNode {
> // +offset: 0
> // +raw: "TrUe"
> // +value: true
> // }
> ```
> {style="warning"}
> <tooltip term="Identifier">Identifiers</tooltip> cannot begin with
digits (`0-9`) or a dash (`-`) symbol.
> ```typescript
> 42type
>
> // Syntax error, unexpected "type"
> ```
> {style="warning"}
</tab>
</tabs>
## Namespace
Each name can contain a namespace symbol (`\` — backslash), which is [similar to that in PHP](https://www.php.net/manual/en/language.namespaces.rationale.php). The separator
can be located either in the middle or at the beginning of any type name. End position is not allowed.
Each name can contain a namespace symbol (`\` — backslash), which is
[similar to that in PHP](https://www.php.net/manual/en/language.namespaces.rationale.php). The separator can be located either in
the middle or at the beginning of any <tooltip
term="Identifier">Identifier</tooltip>. End position is not allowed.
The namespace delimiter can be used in conjunction with keywords such as `true`, `false`, or `null` to explicitly
indicate a type reference.
The namespace delimiter can be used in conjunction with keywords such
as `true`, `false`, or `null` to explicitly indicate a type reference.
<tabs>
<tab title="examples">
* ✔️ **example\name** — Relative class <tooltip term="FQN">FQN</tooltip>.
* ✔️ **\prefixed\example\name** — Absolute class <tooltip term="FQN">FQN</tooltip>.
> Relative class <tooltip term="FQN">FQN</tooltip> reference.
> ```typescript
> Example\Name
> ```
> {style="note"}
> Absolute class <tooltip term="FQN">FQN</tooltip> reference.
> ```typescript
> \Absolute\Type\Name
> ```
> {style="note"}
</tab>
<tab title="counterexamples">
* ❌ **true\null** — Reserved name.
* ❌ **example\name\\** — Trailing delimiter.
* ❌ **example\2type** — Name starts with a number.
> <tooltip term="Identifier">Identifiers</tooltip> cannot contain keywords
> reserved for literal values.
> ```typescript
> true\null
>
> // Syntax error, unexpected "\"
> ```
> {style="warning"}
> <tooltip term="FQN">FQN</tooltip> type names cannot end in `\` delimiter.
> ```typescript
> example\name\
>
> // Syntax error, unexpected end of input
> ```
> {style="warning"}
</tab>
</tabs>
100 changes: 92 additions & 8 deletions Writerside/topics/language/generic-types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,81 @@ comma (`,`).
<tabs>
<tab title="examples">

* ✔️ **example\<T>**
* ✔️ **iterable\<int<0, max>, non-empty-string>**
* ✔️ **HashMap\<Request, User,>** — Trailing comma is allowed.
> Reference to an existing class, interface or enum with template arguments.
> ```typescript
> Path\To\ExampleClass<T, U>
> ```
> {style="note"}
> Reference to builtin type with template arguments containing other generics.
> ```typescript
> iterable<int<0, max>, Collection<User>>
> ```
> {style="note"}
> Trailing comma is allowed.
> ```typescript
> HashMap<Request, User,>
> ```
> {style="note"}
</tab>
<tab title="counterexamples">
* ❌ **example<>** — Missing template argument.
* ❌ **example<,T>** — Leading comma is not allowed.
> Missing template argument.
> ```typescript
> example<>
>
> // Syntax error, unexpected ">"
> ```
> {style="warning"}
> Leading comma is NOT allowed.
> ```typescript
> example<,T>
>
> // Syntax error, unexpected ","
> ```
> {style="warning"}
</tab>
</tabs>
### Call-Site Hints
Each generic argument allows you to define an additional hint, which can
be used, for example, in static analyzers to indicate the
[call-site variance](https://phpstan.org/blog/guide-to-call-site-generic-variance#call-site-variance).
<tabs>
<tab title="examples">
> Any identifier (in this case "`covariant`") before the template argument`s type is acceptable.
> ```typescript
> HashMap<array-key, covariant Request>
> ```
> {style="note"}
</tab>
<tab title="counterexamples">
> Only valid identifiers are allowed.
> ```typescript
> Collection<42 User>
>
> // Syntax error, unexpected "User"
> ```
> {style="warning"}
> Multiple hints are not allowed.
> ```typescript
> HashMap<array-key, some covariant Request>
>
> // Syntax error, unexpected "Request"
> ```
> {style="warning"}
</tab>
</tabs>
Expand All @@ -43,11 +110,28 @@ In addition to modern list declarations such as `list<int>` or
<tabs>
<tab title="examples">
* ✔️ **User\[]** — Correct (list of `User` type).
* ✔️ **User\[]\[]** — Correct (list of lists of `User` type, similar to `list<list<User>>`).
> List (array) of `User` objects.
> ```typescript
> User[]
> ```
> {style="note"}
> List of list (nested array) of `User` objects.
> ```typescript
> User[][]
> ```
> {style="note"}
</tab>
<tab title="counterexamples">
* ❌ **User\[int]** — Incorrect syntax (was [used in the PSR](https://github.com/php-fig/event-dispatcher/blob/1.0.0/src/ListenerProviderInterface.php#L14) by mistake).
> Incorrect syntax (was [used in the PSR](https://github.com/php-fig/event-dispatcher/blob/1.0.0/src/ListenerProviderInterface.php#L14) by mistake).
> ```typescript
> User[int]
>
> // Syntax error, unexpected "int"
> ```
> {style="warning"}
</tab>
</tabs>
Loading

0 comments on commit 9957882

Please sign in to comment.