Update readme

Author: kimdv

README.md

@@ -13,10 +13,11 @@ Its API is designed for performance-critical applications. It uses value types a
 ## Usage
 
 ### Declare SwiftPM dependency with release tag
+
 Add this repository to the `Package.swift` manifest of your project:
 
 ```swift
-// swift-tools-version:5.2
+// swift-tools-version:5.3
 import PackageDescription
 
 let package = Package(
@@ -32,46 +33,42 @@ let package = Package(
 
 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 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 |
 
-
 Then, import `SwiftSyntax` in your Swift code.
 
-
 ### Declare SwiftPM dependency with nightly build
 
 1. Download and install the latest Trunk Development [toolchain](https://swift.org/download/#snapshots).
 
 2. Define the `TOOLCHAINS` environment variable as below to have the `swift` command point inside the toolchain:
-
-```
-$ export TOOLCHAINS=swift
-```
+    ```bash
+    $ export TOOLCHAINS=swift
+    ```
 
 3. To make sure everything is set up correctly, check the result of `xcrun --find swift`. It should point inside the OSS toolchain.
 
 4. Add this entry to the `Package.swift` manifest of your project:
 
-```swift
-// swift-tools-version:4.2
-import PackageDescription
-
-let package = Package(
-  name: "MyTool",
-  dependencies: [
-    .package(url: "https://github.com/apple/swift-syntax.git", .revision("swift-DEVELOPMENT-SNAPSHOT-2019-02-26")),
-  ],
-  targets: [
-    .target(name: "MyTool", dependencies: ["SwiftSyntax"]),
-  ]
-)
-```
+    ```swift
+    // swift-tools-version:5.3
+    import PackageDescription
+
+    let package = Package(
+      name: "MyTool",
+      dependencies: [
+        .package(url: "https://github.com/apple/swift-syntax.git", .revision("swift-DEVELOPMENT-SNAPSHOT-2019-02-26")),
+      ],
+      targets: [
+        .target(name: "MyTool", dependencies: ["SwiftSyntax"]),
+      ]
+    )
+    ```
 
 Tags will be created for every nightly build in the form of `swift-DEVELOPMENT-SNAPSHOT-<DATE>`. The revision field
 should be specified with the intended tag.
@@ -85,7 +82,7 @@ SwiftSyntax depends on the `lib_InternalSwiftSyntaxParser.dylib/.so` library whi
 
 You can either copy `lib_InternalSwiftSyntaxParser.dylib/.so` directly from the toolchain or even build it yourself from the [Swift repository](https://github.com/apple/swift), as long as you are matching the same tags or branches in both the SwiftSyntax and Swift repositories. To build it for the host os (macOS/linux) use the following steps:
 
-```
+```bash
 git clone https://github.com/apple/swift.git
 ./swift/utils/update-checkout --clone
 ./swift/utils/build-parser-lib --release --no-assertions --build-dir /tmp/parser-lib-build
@@ -95,7 +92,7 @@ git clone https://github.com/apple/swift.git
 
 You need to build `lib_InternalSwiftSyntaxParser.dylib` yourself, you cannot copy it from the toolchain. Follow the instructions above and change the invocation of `build-parser-lib` accordingly:
 
-```
+```bash
 ./swift/utils/build-parser-lib --release --no-assertions --build-dir /tmp/parser-lib-build-iossim --host iphonesimulator --architectures x86_64
 ./swift/utils/build-parser-lib --release --no-assertions --build-dir /tmp/parser-lib-build-ios --host iphoneos --architectures arm64
 ```
@@ -143,28 +140,26 @@ Since SwiftSyntax relies on definitions in the main Swift repository to generate
 To build the `main` branch of SwiftSyntax, follow the following instructions:
 
 1. Check `swift-syntax` and  `swift` out side by side:
-
-```
-- (enclosing directory)
-  - swift
-  - swift-syntax
-```
+    ```
+    - (enclosing directory)
+      - swift
+      - swift-syntax
+    ```
 
 2. Make sure you have a recent [Trunk Swift Toolchain](https://swift.org/download/#snapshots) installed.
 3. Define the `TOOLCHAINS` environment variable as below to have the `swift` command point inside the toolchain:
 
-```
-$ export TOOLCHAINS=swift
-```
+    ```bash
+    $ export TOOLCHAINS=swift
+    ```
 
 4. To make sure everything is set up correctly, check the return statement of `xcrun --find swift`. It should point inside the latest installed trunk development toolchain. If it points inside an Xcode toolchain, check that you exported the `TOOLCHAINS` environment variable correctly. If it points inside a version-specific toolchain (like Swift 5.0-dev), you'll need to remove that toolchain.
 5. Run `swift-syntax/build-script.py`.
+    If despite following those instructions, you get compiler errors, the Swift toolchain might be too old to contain recent changes in Swift's SwiftSyntaxParser C library. In that case, you'll have to build the compiler and SwiftSyntax together with the following command:
 
-If despite following those instructions, you get compiler errors, the Swift toolchain might be too old to contain recent changes in Swift's SwiftSyntaxParser C library. In that case, you'll have to build the compiler and SwiftSyntax together with the following command:
-
-```
-$ swift/utils/build-script --swiftsyntax --swiftpm --llbuild
-```
+    ```bash
+    $ swift/utils/build-script --swiftsyntax --swiftpm --llbuild
+    ```
 
 Swift-CI will automatically run the code generation step whenever a new toolchain (development snapshot or release) is published. It should thus almost never be necessary to perform the above build yourself.
 
@@ -173,12 +168,15 @@ Afterward, SwiftPM can also generate an Xcode project to develop SwiftSyntax by
 If you also want to run tests locally, read the section below as testing has additional requirements.
 
 ### Local Testing
+
 SwiftSyntax uses some test utilities that need to be built as part of the Swift compiler project. To build the most recent version of SwiftSyntax and test it, follow the steps in [swift/README.md](https://github.com/apple/swift/blob/main/README.md) and pass `--llbuild --swiftpm --swiftsyntax` to the build script invocation to build SwiftSyntax and all its dependencies using the current trunk (`main`) compiler.
 
 SwiftSyntax can then be tested using the build script in `apple/swift` by running
-```
+
+```bash
 swift/utils/build-script --swiftsyntax --swiftpm --llbuild -t --skip-test-cmark --skip-test-swift --skip-test-llbuild --skip-test-swiftpm
 ```
+
 This command will build SwiftSyntax and all its dependencies, tell the build script to run tests, but skip all tests but the SwiftSyntax tests.
 
 Note that it is not currently supported by SwiftSyntax while building the Swift compiler using Xcode.
@@ -244,5 +242,4 @@ let y = 3001
 
 ## License
 
- Please see [LICENSE](LICENSE.txt) for more information. 
-
+ Please see [LICENSE](LICENSE.txt) for more information.

Sources/SwiftSyntaxBuilder/README.md

@@ -1,30 +1,70 @@
-# SwiftSyntaxBuilder
+# Swift Syntax Builder
 
-Declarative and type-safe wrapper around SwiftSyntax.
+**Swift Syntax Builder** is an open-source package for generating Swift code in a declarative way.
 
-## Example Usage
+> Note: SwiftSyntaxBuilder is still in development, and the API is not guaranteed to
+> be stable. It's subject to change without warning.
 
 ```swift
-let sourceFile = SourceFile {
-  Import("SwiftSyntax")
+import SwiftSyntaxBuilder
 
-  Struct("ExampleStruct") {
-    Let("syntax", of: "Syntax")
-  }
+let source = SourceFile {
+  ImportDecl(path: "Foundation")
+  ImportDecl(path: "UIKit")
+  ClassDecl(classOrActorKeyword: .class, identifier: "SomeViewController", membersBuilder: {
+    VariableDecl(.let, name: "tableView", type: "UITableView")
+  })
 }
 
-let syntax = sourceFile.buildSyntax(format: format, leadingTrivia: .zero)
+let syntax = source.buildSyntax(format: Format())
 
 var text = ""
 syntax.write(to: &text)
+
 print(text)
 ```
 
 prints:
 
 ```swift
-import SwiftSyntax
-struct ExampleStruct {
-  let syntax: Syntax
+import Foundation
+import UIKit
+class SomeViewController{
+    let tableView: UITableView
 }
 ```
+
+## Usage
+
+### Declare SwiftPM dependency with release tag
+
+Add this repository to the `Package.swift` manifest of your project:
+
+```swift
+// swift-tools-version:5.3
+import PackageDescription
+
+let package = Package(
+  name: "MyTool",
+  dependencies: [
+    .package(name: "SwiftSyntax", url: "https://github.com/apple/swift-syntax.git", .exact("<#Specify Release tag#>")),
+  ],
+  targets: [
+    .target(name: "MyTool", dependencies: ["SwiftSyntaxBuilder"]),
+  ]
+)
+```
+
+Replace `<#Specify Release tag#>` by the version of SwiftSyntaxBuilder that you want to use. See this following [table](https://github.com/apple/swift-syntax#declare-swiftpm-dependency-with-release-tag) for mapping details.
+
+Then, import `SwiftSyntaxBuilder` in your Swift code.
+
+Note that SwiftSyntaxBuilder has limited support for pretty-printing code. We generally suggest running a formatter like [swift-format](https://github.com/apple/swift-format) on the generated code.
+
+### Reporting Issues
+
+If you should hit any issues while using SwiftSyntaxBuilder, we appreciate bug reports on [bugs.swift.org](https://bugs.swift.org) in the [SwiftSyntax component](https://bugs.swift.org/issues/?jql=component%20%3D%20SwiftSyntax).
+
+## License
+
+Please see [LICENSE](https://github.com/apple/swift-syntax#license) for more information.