Skip to content

Commit b2cbece

Browse files
kimdvkimdv
authored
Merge pull request #2153 from kimdv/kimdv/add-some-documentation
Add more documentation do Syntax nodes
2 parents 7591cf8 + 8095caf commit b2cbece

File tree

13 files changed

+320
-73
lines changed

13 files changed

+320
-73
lines changed

‎CodeGeneration/Sources/SyntaxSupport/AvailabilityNodes.swift

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,12 @@ public let AVAILABILITY_NODES: [Node] = [
3939
kind: .node(kind: .availabilityLabeledArgument)
4040
),
4141
]),
42-
documentation: "The actual argument"
42+
documentation: "The actual argument."
4343
),
4444
Child(
4545
name: "trailingComma",
4646
kind: .token(choices: [.token(.comma)]),
47-
documentation: "A trailing comma if the argument is followed by another argument",
47+
documentation: "A trailing comma if the argument is followed by another argument.",
4848
isOptional: true
4949
),
5050
]
@@ -66,12 +66,12 @@ public let AVAILABILITY_NODES: [Node] = [
6666
.keyword(.deprecated),
6767
]),
6868
nameForDiagnostics: "label",
69-
documentation: "The label of the argument"
69+
documentation: "The label of the argument."
7070
),
7171
Child(
7272
name: "colon",
7373
kind: .token(choices: [.token(.colon)]),
74-
documentation: "The colon separating label and value"
74+
documentation: "The colon separating label and value."
7575
),
7676
Child(
7777
name: "value",
@@ -86,7 +86,7 @@ public let AVAILABILITY_NODES: [Node] = [
8686
),
8787
]),
8888
nameForDiagnostics: "value",
89-
documentation: "The value of this labeled argument"
89+
documentation: "The value of this labeled argument."
9090
),
9191
]
9292
),
@@ -136,12 +136,12 @@ public let AVAILABILITY_NODES: [Node] = [
136136
Child(
137137
name: "period",
138138
kind: .token(choices: [.token(.period)]),
139-
documentation: "The period of this version component"
139+
documentation: "The period of this version component."
140140
),
141141
Child(
142142
name: "number",
143143
kind: .token(choices: [.token(.integerLiteral)]),
144-
documentation: "The version number of this component"
144+
documentation: "The version number of this component."
145145
),
146146
]
147147
),
@@ -167,7 +167,7 @@ public let AVAILABILITY_NODES: [Node] = [
167167
Child(
168168
name: "components",
169169
kind: .collection(kind: .versionComponentList, collectionElementName: "VersionComponent"),
170-
documentation: "Any version components that are not the major version . For example, for `1.2.0`, this will contain `.2.0`"
170+
documentation: "Any version components that are not the major version . For example, for `1.2.0`, this will contain `.2.0`."
171171
),
172172
]
173173
),

‎CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@ public let COMMON_NODES: [Node] = [
6363
children: [
6464
Child(
6565
name: "leftBrace",
66-
kind: .token(choices: [.token(.leftBrace)])
66+
kind: .token(choices: [.token(.leftBrace)]),
67+
documentation: "The brace introducing the code block."
6768
),
6869
Child(
6970
name: "statements",
@@ -72,7 +73,8 @@ public let COMMON_NODES: [Node] = [
7273
),
7374
Child(
7475
name: "rightBrace",
75-
kind: .token(choices: [.token(.rightBrace)])
76+
kind: .token(choices: [.token(.rightBrace)]),
77+
documentation: "The brace closing the code block."
7678
),
7779
]
7880
),
@@ -88,11 +90,13 @@ public let COMMON_NODES: [Node] = [
8890
Child(
8991
name: "asyncSpecifier",
9092
kind: .token(choices: [.keyword(.async)]),
93+
documentation: "The `async` keyword.",
9194
isOptional: true
9295
),
9396
Child(
9497
name: "throwsSpecifier",
9598
kind: .token(choices: [.keyword(.throws)]),
99+
documentation: "The `throws` keyword.",
96100
isOptional: true
97101
),
98102
]
@@ -109,11 +113,13 @@ public let COMMON_NODES: [Node] = [
109113
Child(
110114
name: "asyncSpecifier",
111115
kind: .token(choices: [.keyword(.async), .keyword(.reasync)]),
116+
documentation: "The `async` or `reasync` keyword.",
112117
isOptional: true
113118
),
114119
Child(
115120
name: "throwsSpecifier",
116121
kind: .token(choices: [.keyword(.throws), .keyword(.rethrows)]),
122+
documentation: "The `throws` or `rethrows` keyword.",
117123
isOptional: true
118124
),
119125
]
@@ -128,6 +134,7 @@ public let COMMON_NODES: [Node] = [
128134
Child(
129135
name: "asyncSpecifier",
130136
kind: .token(choices: [.keyword(.async)]),
137+
documentation: "The `async` keyword.",
131138
isOptional: true
132139
)
133140
]

‎CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

Lines changed: 30 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ public let DECL_NODES: [Node] = [
5353
children: [
5454
Child(
5555
name: "leftBrace",
56-
kind: .token(choices: [.token(.leftBrace)])
56+
kind: .token(choices: [.token(.leftBrace)]),
57+
documentation: "The brace introducing the accessor block."
5758
),
5859
Child(
5960
name: "accessors",
@@ -70,7 +71,8 @@ public let DECL_NODES: [Node] = [
7071
),
7172
Child(
7273
name: "rightBrace",
73-
kind: .token(choices: [.token(.rightBrace)])
74+
kind: .token(choices: [.token(.rightBrace)]),
75+
documentation: "The brace closing the accessor block."
7476
),
7577
]
7678
),
@@ -183,16 +185,19 @@ public let DECL_NODES: [Node] = [
183185
Child(
184186
name: "modifiers",
185187
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
186-
nameForDiagnostics: "modifiers"
188+
nameForDiagnostics: "modifiers",
189+
documentation: "Modifiers like `public` that are attached to the actor declaration."
187190
),
188191
Child(
189192
name: "actorKeyword",
190-
kind: .token(choices: [.keyword(.actor)])
193+
kind: .token(choices: [.keyword(.actor)]),
194+
documentation: "The `actor` keyword."
191195
),
192196
Child(
193197
name: "name",
194198
deprecatedName: "identifier",
195-
kind: .token(choices: [.token(.identifier)])
199+
kind: .token(choices: [.token(.identifier)]),
200+
documentation: "The name of the actor. If the name matches a reserved keyword use backticks to escape it."
196201
),
197202
Child(
198203
name: "genericParameterClause",
@@ -268,7 +273,7 @@ public let DECL_NODES: [Node] = [
268273
name: "modifiers",
269274
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
270275
nameForDiagnostics: "modifiers",
271-
documentation: "Modifiers attached to the associated type declaration."
276+
documentation: "Modifiers like `public` that are attached to the associated type declaration."
272277
),
273278
Child(
274279
name: "associatedtypeKeyword",
@@ -351,7 +356,7 @@ public let DECL_NODES: [Node] = [
351356
name: "modifiers",
352357
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
353358
nameForDiagnostics: "modifiers",
354-
documentation: "Modifiers attached to the class declaration, such as `public`."
359+
documentation: "Modifiers like `public` that are attached to the class declaration."
355360
),
356361
Child(
357362
name: "classKeyword",
@@ -499,12 +504,12 @@ public let DECL_NODES: [Node] = [
499504
name: "modifiers",
500505
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
501506
nameForDiagnostics: "modifiers",
502-
documentation: "Modifiers that are attached to the deinitializer."
507+
documentation: "Modifiers like `public` that are attached to the deinitializer."
503508
),
504509
Child(
505510
name: "deinitKeyword",
506511
kind: .token(choices: [.keyword(.deinit)]),
507-
documentation: "The deinit keyword."
512+
documentation: "The `deinit` keyword."
508513
),
509514
Child(
510515
name: "effectSpecifiers",
@@ -702,7 +707,7 @@ public let DECL_NODES: [Node] = [
702707
kind: .enumCaseElementList,
703708
base: .syntaxCollection,
704709
nameForDiagnostics: nil,
705-
documentation: "A collection of 0 or more `EnumCaseElement`s.",
710+
documentation: "A collection of 0 or more ``EnumCaseElementSyntax``s.",
706711
elementChoices: [.enumCaseElement]
707712
),
708713

@@ -829,7 +834,8 @@ public let DECL_NODES: [Node] = [
829834
Child(
830835
name: "modifiers",
831836
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
832-
nameForDiagnostics: "modifiers"
837+
nameForDiagnostics: "modifiers",
838+
documentation: "Modifiers like `public` that are attached to the extension declaration."
833839
),
834840
Child(
835841
name: "extensionKeyword",
@@ -854,7 +860,9 @@ public let DECL_NODES: [Node] = [
854860
),
855861
Child(
856862
name: "memberBlock",
857-
kind: .node(kind: .memberBlock)
863+
kind: .node(kind: .memberBlock),
864+
documentation:
865+
"The members of the extension declaration. As this is an extension, the contents of this member block isn't guaranteed to be a complete list of members for this type."
858866
),
859867
]
860868
),
@@ -878,7 +886,8 @@ public let DECL_NODES: [Node] = [
878886
Child(
879887
name: "modifiers",
880888
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
881-
nameForDiagnostics: "modifiers"
889+
nameForDiagnostics: "modifiers",
890+
documentation: "Modifiers like `public` that are attached to the function declaration."
882891
),
883892
Child(
884893
name: "funcKeyword",
@@ -892,7 +901,8 @@ public let DECL_NODES: [Node] = [
892901
.token(.binaryOperator),
893902
.token(.prefixOperator),
894903
.token(.postfixOperator),
895-
])
904+
]),
905+
documentation: "The name of the function. If the name matches a reserved keyword use backticks to escape it."
896906
),
897907
Child(
898908
name: "genericParameterClause",
@@ -1103,7 +1113,7 @@ public let DECL_NODES: [Node] = [
11031113
name: "modifiers",
11041114
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
11051115
nameForDiagnostics: "modifiers",
1106-
documentation: "Modifiers attached to the import declaration. Currently, no modifiers are supported by Swift."
1116+
documentation: "Modifiers that are attached to the import declaration. Currently, no modifiers are supported by Swift."
11071117
),
11081118
Child(
11091119
name: "importKeyword",
@@ -1216,7 +1226,7 @@ public let DECL_NODES: [Node] = [
12161226
name: "modifiers",
12171227
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
12181228
nameForDiagnostics: "modifiers",
1219-
documentation: "Modifiers attached to the initializer"
1229+
documentation: "Modifiers that are attached to the initializer declaration."
12201230
),
12211231
Child(
12221232
name: "initKeyword",
@@ -1249,7 +1259,7 @@ public let DECL_NODES: [Node] = [
12491259
name: "genericWhereClause",
12501260
kind: .node(kind: .genericWhereClause),
12511261
nameForDiagnostics: "generic where clause",
1252-
documentation: "If the initializer had generic parameters, a where clause that can restrict those",
1262+
documentation: "If the initializer had generic parameters, a where clause that can restrict those.",
12531263
isOptional: true
12541264
),
12551265
Child(
@@ -2019,7 +2029,7 @@ public let DECL_NODES: [Node] = [
20192029
name: "modifiers",
20202030
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
20212031
nameForDiagnostics: "modifiers",
2022-
documentation: "Modifiers that are attached to the struct declaration."
2032+
documentation: "Modifiers like `public` that are attached to the struct declaration."
20232033
),
20242034
Child(
20252035
name: "structKeyword",
@@ -2227,7 +2237,8 @@ public let DECL_NODES: [Node] = [
22272237
Child(
22282238
name: "modifiers",
22292239
kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
2230-
nameForDiagnostics: "modifiers"
2240+
nameForDiagnostics: "modifiers",
2241+
documentation: "Modifiers modifiers applied to the variable declaration."
22312242
),
22322243
Child(
22332244
name: "bindingSpecifier",

‎CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ public let EXPR_NODES: [Node] = [
106106
```
107107
108108
```swift
109-
myPet as? Dog`
109+
myPet as? Dog
110110
```
111111
112112
- Note: This node is only generated after operators are folded using the `SwiftOperators` library.
@@ -1733,30 +1733,49 @@ public let EXPR_NODES: [Node] = [
17331733
kind: .switchExpr,
17341734
base: .expr,
17351735
nameForDiagnostics: "'switch' statement",
1736+
documentation: """
1737+
A `switch` expression.
1738+
1739+
### Examples
1740+
1741+
This represents the switch expression in
1742+
1743+
```swift
1744+
switch self.foo {
1745+
}
1746+
```
1747+
1748+
A switch ecpression may be declared without any cases.
1749+
""",
17361750
traits: [
17371751
"Braced"
17381752
],
17391753
children: [
17401754
Child(
17411755
name: "switchKeyword",
1742-
kind: .token(choices: [.keyword(.switch)])
1756+
kind: .token(choices: [.keyword(.switch)]),
1757+
documentation: "The `switch` keyword."
17431758
),
17441759
Child(
17451760
name: "subject",
17461761
deprecatedName: "expression",
1747-
kind: .node(kind: .expr)
1762+
kind: .node(kind: .expr),
1763+
documentation: "The expression to switch over."
17481764
),
17491765
Child(
17501766
name: "leftBrace",
1751-
kind: .token(choices: [.token(.leftBrace)])
1767+
kind: .token(choices: [.token(.leftBrace)]),
1768+
documentation: "The brace introducing the switch body."
17521769
),
17531770
Child(
17541771
name: "cases",
1755-
kind: .collection(kind: .switchCaseList, collectionElementName: "Case")
1772+
kind: .collection(kind: .switchCaseList, collectionElementName: "Case"),
1773+
documentation: "The switch's body that contains all possible cases."
17561774
),
17571775
Child(
17581776
name: "rightBrace",
1759-
kind: .token(choices: [.token(.rightBrace)])
1777+
kind: .token(choices: [.token(.rightBrace)]),
1778+
documentation: "The brace closing the switch body."
17601779
),
17611780
]
17621781
),

0 commit comments

Comments
 (0)