Skip to content

Commit e8fc865

Browse files
committed
Update ChangingSwiftSyntax.md
Update some outdated comments from ChangingSwiftSyntax.md
1 parent 7ce21f8 commit e8fc865

File tree

1 file changed

+28
-47
lines changed

1 file changed

+28
-47
lines changed

Sources/SwiftSyntax/Documentation.docc/Contributing/ChangingSwiftSyntax.md

Lines changed: 28 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -12,31 +12,27 @@ structures in sync, this project generates code using the Swift package
1212
## Regenerating Files
1313

1414
To re-generate the files after changing `CodeGeneration` run the `generate-swiftsyntax`
15-
target of `CodeGeneration` and pass `path/to/swift-syntax/Sources` as the argument.
15+
target of `CodeGeneration`.
1616

1717
On the command line, this would be
1818
```bash
19-
swift run --package-path CodeGeneration generate-swiftsyntax Sources
19+
swift run --package-path CodeGeneration generate-swiftsyntax
2020
```
2121

22-
Or if you open the `CodeGeneration` package in Xcode, you can add the
23-
`generate-swift syntax ../Sources` arguments using Product -> Scheme -> Edit Scheme…
24-
2522
## Adding and Removing Syntax Nodes
2623

2724
The files containing the definition of all of the syntax nodes are available
28-
under the [SyntaxSupport][SyntaxSupport] directory. These files
25+
under the [SyntaxSupport](SyntaxSupport) directory. These files
2926
are roughly divided according to broad syntactic categories in the Swift
3027
programming language. That is, the syntax nodes for classes, structs, and actors
31-
are defined in `DeclNodes.py`, while the syntax nodes for string literals,
32-
arrays, and tuples is defined in `ExprNodes.py`.
28+
are defined in `DeclNodes.swift`, while the syntax nodes for string literals,
29+
arrays, and tuples is defined in `ExprNodes.swift`.
3330

3431
To add a node to these files, it can be helpful to copy an existing node and
3532
alter its definition to suit the needs of the new syntax being defined. A syntax
36-
node consists of a name, a kind, and a list of child nodes. The name of a node
37-
not only identifies it uniquely to Swift Syntax, it also provides a handle that
38-
other nodes can use to refer to it. The kind of a syntax node defines the
39-
class of syntax the node belongs to. All nodes are at least of the `Syntax`
33+
node consists of a kind (which also defines the node’s name), a base kind, and a list of
34+
child nodes. The base kind of a syntax node defines the class of syntax the node belongs to.
35+
All nodes are at least of the `Syntax`
4036
kind, though some nodes may have a more specific kind like `Stmt` for
4137
statements or `Expr` for expressions. The SwiftSyntax library expands these
4238
kinds into protocol conformances and allows for casting strongly typed syntax
@@ -45,33 +41,29 @@ nodes among these categories for easier processing.
4541
The node for a source file is reproduced below:
4642

4743
```swift
48-
Node(
49-
name: "SourceFile",
50-
nameForDiagnostics: "source file",
51-
kind: "Syntax",
52-
traits: [
53-
"WithStatements"
54-
],
55-
parserFunction: "parseSourceFile",
56-
children: [
57-
Child(
58-
name: "Statements",
59-
kind: .collection(kind: "CodeBlockItemList", collectionElementName: "Statement")
60-
),
61-
Child(
62-
name: "EOFToken",
63-
kind: .node(kind: "EOFToken")
64-
),
65-
]
66-
),
67-
44+
Node(
45+
kind: .sourceFile,
46+
base: .syntax,
47+
nameForDiagnostics: "source file",
48+
parserFunction: "parseSourceFile",
49+
traits: ["WithStatements"],
50+
children: [
51+
Child(
52+
name: "Statements",
53+
kind: .collection(kind: .codeBlockItemList, collectionElementName: "Statement")
54+
),
55+
Child(
56+
name: "EndOfFileToken",
57+
deprecatedName: "EOFToken",
58+
kind: .token(choices: [.token(tokenKind: "EndOfFileToken")])
59+
),
60+
]
61+
)
6862
```
6963

7064
## Committing Changes
7165

72-
When it is time to commit changes to the Swift Syntax repository, most cases
73-
of adding syntax will require a single PR to swift-syntax. Added
74-
syntactic elements will require corresponding changes to the included
66+
Added syntactic elements will require corresponding changes to the included
7567
SwiftParser library. For an introduction on parsing Swift nodes, see
7668
[the article on Parsing Basics][ParserBasics].
7769

@@ -82,21 +74,10 @@ SwiftParser library. For an introduction on parsing Swift nodes, see
8274

8375
When updating nodes, certain clients of SwiftSyntax that are relying upon those
8476
nodes will need to be changed in tandem. For example, the
85-
[swift-stress-tester][swift-stress-tester] uses SwiftSyntax, and the CI/CD
77+
[swift-stress-tester][swift-stress-tester] uses SwiftSyntax, and the CI
8678
system will not allow changes to SwiftSyntax that break `swift-stress-tester`
8779
without a paired change to that repository.
8880

89-
When adding nodes or removing existing nodes, it is often the case that you
90-
will need a paired PR to the [Swift Compiler repository][Swiftc] as well. This
91-
step currently involves some amount of duplication with the SwiftParser library
92-
and is a much more involved process. [The Swift Forums][CompilerDev] are a
93-
great source for guidance on how to extend the C++ compiler to accommodate new
94-
syntax and semantics for the Swift programming language.
95-
96-
[LiterateProgramming]: https://en.wikipedia.org/wiki/Literate_programming
97-
[SwiftToolchains]: https://www.swift.org/download/
9881
[SyntaxSupport]: https://github.com/apple/swift-syntax/tree/main/CodeGeneration/Sources/SyntaxSupport
9982
[swift-stress-tester]: https://github.com/apple/swift-stress-tester
100-
[Swiftc]: https://github.com/apple/swift
10183
[ParserBasics]: https://github.com/apple/swift-syntax/tree/main/Sources/SwiftParser/SwiftParser.docc/ParsingBasics.md
102-
[CompilerDev]: https://forums.swift.org/c/development/compiler/

0 commit comments

Comments
 (0)