Merge pull request #2212 from ahoppen/ahoppen/update-readme

Update README.md

Examples/README.md

@@ -5,6 +5,7 @@ Each example can be executed by navigating into this folder and running `swift r
 - [AddOneToIntegerLiterals](Sources/AddOneToIntegerLiterals/AddOneToIntegerLiterals.swift): Command line tool to add 1 to every integer literal in a source file
 - [CodeGenerationUsingSwiftSyntaxBuilder](Sources/CodeGenerationUsingSwiftSyntaxBuilder/CodeGenerationUsingSwiftSyntaxBuilder.swift): Code-generate a simple source file using SwiftSyntaxBuilder
 - [ExamplePlugin](Sources/ExamplePlugin): Compiler plugin executable using [`SwiftCompilerPlugin`](../Sources/SwiftCompilerPlugin)
+- [MacroExamples](Sources/MacroExamples): A collection of Swift macros
 
 Furthermore, SwiftSyntax uses [`SwiftSyntaxBuilder`](../Sources/SwiftSyntaxBuilder) extensively to generate its own code. That code can be found in the [CodeGeneration](../CodeGeneration) package.
 

README.md

@@ -1,106 +1,38 @@
-# SwiftSyntax
+# Swift Syntax
 
-SwiftSyntax is a set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.
+The swift-syntax package is a set of libraries that work on a source-accurate tree representation of Swift source code, called the SwiftSyntax tree. The SwiftSyntax tree forms the backbone of Swift’s macro system – the macro expansion nodes are represented as SwiftSyntax nodes and a macro generates a SwiftSyntax tree to be inserted into the source file.
 
 ## Documentation
 
 You can read SwiftSyntax’s documentation on [swiftpackageindex.com](https://swiftpackageindex.com/apple/swift-syntax/documentation).
 
 A great way to interactively explore the SwiftSyntax tree of a source file is https://swift-ast-explorer.com, developed by [@kishikawakatsumi](https://github.com/kishikawakatsumi).
 
-## Adding SwiftSyntax as a Dependency
+A set of example usages of swift-syntax can be found in [Examples](Examples).
 
-### Trunk Development (main)
+## Releases
 
-The mainline branch of SwiftSyntax tracks the latest developments. It is not
-an official release, and is subject to rapid changes in APIs and behaviors. To 
-use it, add this repository to the `Package.swift` manifest of your project:
+Releases of SwiftSyntax are aligned with corresponding language and tooling releases, for example the major version 509 of swift-syntax is aligned with Swift 5.9. 
+
+To depend on swift-syntax in a SwiftPM package, add the following to your `Package.swift`.
 
-```swift
-// swift-tools-version:5.7
-import PackageDescription
-
-let package = Package(
-  name: "MyTool",
-  dependencies: [
-    .package(url: "https://github.com/apple/swift-syntax.git", branch: "main"),
-  ],
-  targets: [
-    .target(name: "MyTool", dependencies: [
-      .product(name: "SwiftSyntax", package: "swift-syntax"),
-    ]),
-  ]
-)
-```
-
-Mainline SwiftSyntax also includes 
-
-- `SwiftParser` for natively parsing source code
-- `SwiftOperators` for folding SwiftSyntax trees containing operators
-- `SwiftSyntaxBuilder` for generating Swift code with a result builder-style interface
-- `SwiftSyntaxMacros` for providing syntactic macro support
-
-### Releases
-
-Releases of SwiftSyntax are aligned with corresponding language
-and tooling releases and are stable. To use them, 
-add this repository to the `Package.swift` manifest of your project:
 
 ```swift
-// swift-tools-version:5.7
-import PackageDescription
-
-let package = Package(
-  name: "MyTool",
-  dependencies: [
-    .package(url: "https://github.com/apple/swift-syntax.git", exact: "<#Specify Release tag#>"),
-  ],
-  targets: [
-    .target(name: "MyTool", dependencies: [
-      .product(name: "SwiftSyntax", package: "swift-syntax"),
-    ]),
-  ]
-)
+dependencies: [
+  .package(url: "https://github.com/apple/swift-syntax.git", from: "<#latest swift-syntax tag#>"),
+],
 ```
+
+To add swift-syntax as a dependency of your Xcode project, go to the *Package Dependencies* tab of your Xcode project, click the plus button and search for https://github.com/apple/swift-syntax.git.
 
-Replace `<#Specify Release tag#>` by the version of SwiftSyntax that you want to use (see the following table for mapping details).
-
-| Xcode Release | Swift Release Tag | SwiftSyntax Release Tag  |
-|:-------------------:|:-------------------:|:-------------------------:|
-| Xcode 14.3   | swift-5.8-RELEASE   | 508.0.0   |
-| Xcode 14.0   | swift-5.7-RELEASE   | 0.50700.1 |
-| Xcode 13.3   | swift-5.6-RELEASE   | 0.50600.1 |
-| Xcode 13.0   | swift-5.5-RELEASE   | 0.50500.0 |
-| Xcode 12.5   | swift-5.4-RELEASE   | 0.50400.0 |
-| Xcode 12.0   | swift-5.3-RELEASE   | 0.50300.0 |
-| Xcode 11.4   | swift-5.2-RELEASE   | 0.50200.0 |
-
-## Documentation
-
-SwiftSyntax uses [DocC](https://developer.apple.com/documentation/docc) bundles
-for its documentation. To view rendered documentation in Xcode, open the 
-SwiftSyntax package and select
-
-```
-Product > Build Documentation
-``` 
-
-Associated articles are written in markdown, and can be viewed in a browser, 
-text editor, or IDE.
+## Reporting Issues
 
-- [SwiftSyntax](Sources/SwiftSyntax/Documentation.docc)
-- [SwiftParser](Sources/SwiftParser/SwiftParser.docc)
-- [SwiftOperators](Sources/SwiftOperators/SwiftOperators.docc)
-- [SwiftSyntaxMacros](Sources/SwiftSyntaxMacros/SwiftSyntaxMacros.docc)
+If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues).
 
 ## Contributing
 
 Start contributing to SwiftSyntax see [this guide](CONTRIBUTING.md) for more information.
 
-## Reporting Issues
-
-If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues).
-
 ## Bazel
 
 SwiftSyntax provides an experimental [Bazel](https://bazel.build) build configuration, maintained by Keith Smiley.