11# Specification
22
3- ** Version** : 1.0.0
3+ ** Version** : 1.0.1
44
55** Authored By** : Aviv Keller (< me@aviv.sh > )
66
@@ -98,15 +98,9 @@ in the relevant section.
9898 - [ 7.6. Placement] ( #76-placement )
9999- [ 8. Type Annotations] ( #8-type-annotations )
100100 - [ 8.1. Syntax] ( #81-syntax )
101- - [ 8.2. Primitive Types] ( #82-primitive-types )
102- - [ 8.3. Global Types] ( #83-global-types )
103- - [ 8.4. Custom Types] ( #84-custom-types )
104- - [ 8.5. Compound Types] ( #85-compound-types )
105- - [ 8.5.1. Union Types] ( #851-union-types )
106- - [ 8.5.2. Array Types] ( #852-array-types )
107- - [ 8.5.3. Generic Types] ( #853-generic-types )
108- - [ 8.6. Resolution Order] ( #86-resolution-order )
109- - [ 8.7. Unresolved Types] ( #87-unresolved-types )
101+ - [ 8.2. Parsing] ( #82-parsing )
102+ - [ 8.3. Resolution] ( #83-resolution )
103+ - [ 8.4. Rendering] ( #84-rendering )
110104- [ 9. Typed Parameter Lists] ( #9-typed-parameter-lists )
111105 - [ 9.1. Identification] ( #91-identification )
112106 - [ 9.2. Item Structure] ( #92-item-structure )
@@ -178,9 +172,10 @@ providing version-history and classification metadata for the enclosing
178172the compact ` key=value ` pattern, providing [ document] [ term-document ] -level or
179173[ section] [ term-section ] -level metadata. See [ §6.2] [ §6.2 ] .
180174
181- ** Type annotation.** A reference to a type enclosed in ` {curly braces} ` within
182- a [ typed list] [ term-typed-list ] item, or in prose, that is resolved to a
183- hyperlink. See [ §8] [ §8 ] .
175+ ** Type annotation.** A [ TypeScript] [ typescript ] type expression enclosed in
176+ balanced ` {curly braces} ` within a [ typed list] [ term-typed-list ] item, or in
177+ prose. It is rendered as a single code fragment whose type names are resolved
178+ to hyperlinks. See [ §8] [ §8 ] .
184179
185180---
186181
@@ -844,91 +839,61 @@ A [stability indicator][term-stability] on the depth-1 heading applies to the
844839
845840### 8.1. Syntax
846841
847- [ Type annotations] [ term-type-annotation ] are enclosed in curly braces, such as
848- ` {Type} ` . They appear in two contexts:
849-
850- - ** In [ typed parameter lists] [ §9 ] :** as part of item structure.
851- - ** In prose text:** as inline references.
852-
853- Both forms are auto-linked to documentation for the referenced type (see
854- [ §8.6] [ §8.6 ] ).
855-
856- ### 8.2. Primitive Types
857-
858- Primitive types use lowercase names: ` string ` , ` number ` , ` boolean ` , ` bigint ` ,
859- ` symbol ` , ` null ` , ` undefined ` , ` integer ` .
860-
861- These MUST be resolved to documentation for JavaScript primitive data types.
862-
863- ### 8.3. Global Types
864-
865- JavaScript built-in globals use PascalCase: ` Array ` , ` Object ` , ` Function ` ,
866- ` Promise ` , ` Error ` , ` RegExp ` , ` Map ` , ` Set ` , ` Date ` , ` Uint8Array ` , ` Buffer ` ,
867- and others.
868-
869- These MUST be resolved to documentation for JavaScript global objects.
870-
871- ### 8.4. Custom Types
872-
873- Types not in the primitive or global sets are resolved via a configurable type
874- map provided to the toolchain. The type map associates type names with
875- documentation URLs. An example type-map is available for viewing [ here] [ nodejs-typemap ] .
876-
877- ### 8.5. Compound Types
878-
879- #### 8.5.1. Union Types
880-
881- Multiple types are separated by ` | ` (pipe):
882-
883- ```
884- {string|Buffer|URL}
885- ```
886-
887- Spaces around the pipe are OPTIONAL. Both ` {string|Buffer} ` and
888- ` {string | Buffer} ` MUST be accepted.
889-
890- #### 8.5.2. Array Types
891-
892- The ` [] ` suffix denotes an array of the base type:
893-
894- ```
895- {string[]}
896- {Buffer[]}
897- ```
898-
899- #### 8.5.3. Generic Types
900-
901- Generic types use angle brackets:
902-
903- ```
904- {Promise<string>}
905- {Map<string, number>}
906- ```
907-
908- The outer type and each inner type parameter are resolved independently. Inner
909- types MAY include [ unions] [ §8.5.1 ] :
910-
911- ```
912- {Promise<string|Buffer>}
913- ```
914-
915- ### 8.6. Resolution Order
916-
917- Types are resolved in the following order. The first tier that produces a
918- match terminates resolution.
919-
920- 1 . JavaScript primitives (see [ §8.2] [ §8.2 ] ).
921- 2 . JavaScript built-in globals (see [ §8.3] [ §8.3 ] ).
922- 3 . Implementation-defined external type mappings.
923- 4 . Custom type map entries (see [ §8.4] [ §8.4 ] ).
924- 5 . Dotted-name heuristic: types containing ` . ` are split on the first ` . ` to
842+ A [ type annotation] [ term-type-annotation ] is any balanced ` {curly brace} `
843+ span in text. The content between the braces is a [ TypeScript] [ typescript ]
844+ type expression — anything valid on the right-hand side of a TypeScript
845+ ` type X = ... ` alias.
846+
847+ Annotations appear both in [ typed parameter lists] [ §9 ] (as part of item
848+ structure) and in prose text (as inline references); both forms are parsed
849+ and rendered identically.
850+
851+ ### 8.2. Parsing
852+
853+ Implementations MUST parse each annotation whose value is not a whole-value
854+ [ map match] [ §8.3 ] under the TypeScript type grammar. Implementations SHOULD
855+ collect every annotation in a [ document] [ term-document ] and parse them in a
856+ single batch.
857+
858+ An annotation that fails to parse MUST produce a warning identifying the
859+ source location, and MUST be rendered as plain, unlinked code.
860+
861+ ### 8.3. Resolution
862+
863+ Each annotation resolves to a set of hyperlinks:
864+
865+ 1 . ** Whole-value lookup.** If the entire annotation value matches a type-map
866+ entry verbatim, the whole annotation becomes a single link. This permits
867+ display-name keys that are not valid TypeScript identifiers (e.g.
868+ ` zlib options ` ).
869+ 2 . ** Identifier resolution.** Otherwise, every type name in the parsed
870+ expression resolves individually: keyword types (` string ` , ` number ` ,
871+ ` boolean ` , ...), type-reference names, qualified names (` vm.Module ` ),
872+ ` typeof ` targets, and ` import('mod').X ` qualifiers. Structural names —
873+ function parameter names, object property keys — are never resolved.
874+
875+ Each name resolves through the following tiers; the first match wins:
876+
877+ 1 . The configurable type map provided to the toolchain, which associates
878+ names with documentation URLs. An example type map is available for
879+ viewing [ here] [ nodejs-typemap ] .
880+ 2 . JavaScript primitives and built-in (TC39) globals, matched
881+ case-insensitively: ` string ` , ` number ` , ` boolean ` , ` bigint ` , ` symbol ` ,
882+ ` null ` , ` undefined ` , ` integer ` , ` Array ` , ` Object ` , ` Function ` , ` Promise ` ,
883+ and others.
884+ 3 . Web platform APIs documented on MDN, matched case-insensitively.
885+ 4 . Dotted-name heuristic: names containing ` . ` are split on the first ` . ` to
925886 derive a module name and member identifier, producing a cross-document
926887 link of the form ` <module>.md#<identifier> ` .
927888
928- ### 8.7. Unresolved Types
889+ A name that no tier resolves stays plain — this is not an error.
890+
891+ ### 8.4. Rendering
929892
930- If a type cannot be resolved through any tier, it WILL be rendered as
931- unlinked formatted text.
893+ The whole annotation renders as ONE inline code fragment. Each resolved name
894+ becomes a hyperlink spanning exactly its character range within the fragment;
895+ unresolved names remain plain text inside it. Implementations MAY
896+ syntax-highlight the fragment as TypeScript.
932897
933898---
934899
@@ -945,10 +910,9 @@ its first item matches any of these conditions:
945910
9469111 . It begins with text matching one of the [ special prefixes] [ §9.3 ]
947912 (` Returns: ` , ` Extends: ` , ` Type: ` ).
948- 2 . It begins with a [ type-reference] [ §8 ] link (a link whose label is a type
949- annotation such as ` {Type} ` ).
913+ 2 . It begins with a [ type annotation] [ §8 ] .
9509143 . It begins with an inline code span (the parameter name) followed by a
951- space and then a [ type-reference ] [ §8 ] link .
915+ space and then a [ type annotation ] [ §8 ] .
952916
953917### 9.2. Item Structure
954918
@@ -964,7 +928,8 @@ The components, in order, are:
9649282 . ** Parameter name** - A backtick code span. REQUIRED for parameter items;
965929 absent for [ ` Returns: ` ] [ §9.3.1 ] , [ ` Type: ` ] [ §9.3.3 ] , and
966930 [ ` Extends: ` ] [ §9.3.2 ] items.
967- 3 . ** [ Type annotation] [ §8 ] ** - A ` {Type} ` reference. OPTIONAL.
931+ 3 . ** [ Type annotation] [ §8 ] ** - A single ` {...} ` TypeScript type expression
932+ (a union belongs inside it, e.g. ` {string|Buffer} ` ). OPTIONAL.
9689334 . ** Description** - Free-form prose. OPTIONAL.
9699345 . ** [ Default value] [ §9.5 ] ** - The exact pattern ` **Default:** \ ` value\` `.
970935 OPTIONAL.
@@ -1106,9 +1071,9 @@ documentation by conforming implementations.
11061071
11071072### 11.5. Type Auto-Linking
11081073
1109- [ Type annotations] [ term-type-annotation ] in prose text matching the
1110- ` {Type} ` pattern ([ §8.1 ] [ §8.1 ] ) are automatically converted to hyperlinks
1111- following the [ resolution order ] [ §8.6 ] .
1074+ [ Type annotations] [ term-type-annotation ] in prose text ( [ §8.1 ] [ §8.1 ] ) are
1075+ parsed ([ §8.2 ] [ §8.2 ] ), resolved ( [ §8.3 ] [ §8.3 ] ), and rendered ( [ §8.4 ] [ §8.4 ] )
1076+ exactly like annotations in [ typed parameter lists ] [ §9 ] .
11121077
11131078### 11.6. Link Reference Definitions
11141079
@@ -1132,6 +1097,7 @@ of the [document][term-document], after all content
11321097[ rfc-8174 ] : https://www.rfc-editor.org/rfc/rfc8174
11331098[ yaml-1.2 ] : https://yaml.org/spec/1.2.2/
11341099[ semver ] : https://semver.org/
1100+ [ typescript ] : https://www.typescriptlang.org/
11351101[ nodejs-typemap ] : https://github.com/nodejs/node/blob/main/doc/type-map.json
11361102
11371103<!-- CommonMark spec sections -->
@@ -1187,11 +1153,9 @@ of the [document][term-document], after all content
11871153[ §7.3 ] : #73-sub-levels
11881154[ §8 ] : #8-type-annotations
11891155[ §8.1 ] : #81-syntax
1190- [ §8.2 ] : #82-primitive-types
1191- [ §8.3 ] : #83-global-types
1192- [ §8.4 ] : #84-custom-types
1193- [ §8.5.1 ] : #851-union-types
1194- [ §8.6 ] : #86-resolution-order
1156+ [ §8.2 ] : #82-parsing
1157+ [ §8.3 ] : #83-resolution
1158+ [ §8.4 ] : #84-rendering
11951159[ §9 ] : #9-typed-parameter-lists
11961160[ §9.3 ] : #93-special-prefixes
11971161[ §9.3.1 ] : #931-returns
0 commit comments