Add documentation for initializers that build a node from a header and a result builder

rdar://108643660

Author: ahoppen

Sources/SwiftSyntaxBuilder/SyntaxNodeWithBody.swift

@@ -40,6 +40,15 @@ extension SyntaxStringInterpolation {
 public protocol HasTrailingCodeBlock {
   var body: CodeBlockSyntax { get set }
 
+  /// Constructs a syntax node where `header` builds the text of the node before the body in braces and `bodyBuilder` is used to build the node’s body.
+  ///
+  /// For example the following function has header `while x < 5` and the body will contain an `ExprSyntax` with text `x += 1`.
+  ///
+  /// ```swift
+  /// while x < 5 {
+  ///   x += 1
+  /// }
+  /// ```
   init(_ header: PartialSyntaxNodeString, @CodeBlockItemListBuilder bodyBuilder: () throws -> CodeBlockItemListSyntax) rethrows
 }
 
@@ -71,6 +80,15 @@ extension WhileStmtSyntax: HasTrailingCodeBlock {}
 public protocol HasTrailingOptionalCodeBlock {
   var body: CodeBlockSyntax? { get set }
 
+  /// Constructs a syntax node where `header` builds the text of the node before the body in braces and `bodyBuilder` is used to build the node’s body.
+  ///
+  /// For example the following function has header `func addOne(_ base: Int) -> Int` and the body will contain an `ExprSyntax` with text `return base + 1`.
+  ///
+  /// ```swift
+  /// func addOne(_ base: Int) -> Int {
+  ///   return base + 1
+  /// }
+  /// ```
   init(_ header: PartialSyntaxNodeString, @CodeBlockItemListBuilder bodyBuilder: () throws -> CodeBlockItemListSyntax) throws
 }
 
@@ -95,6 +113,16 @@ extension InitializerDeclSyntax: HasTrailingOptionalCodeBlock {}
 public protocol HasTrailingMemberDeclBlock {
   var memberBlock: MemberDeclBlockSyntax { get set }
 
+  /// Constructs a syntax node where `header` builds the text of the node before the members in braces and `membersBuilder` is used to list the node’s members.
+  ///
+  /// For example the following function has header `struct Point` and the body will contain two `DeclSyntax` with text `var x: Int` and `var y: Int`, respecitively.
+  ///
+  /// ```swift
+  /// struct Point {
+  ///   var x: Int
+  ///   var y: Int
+  /// }
+  /// ```
   init(_ header: PartialSyntaxNodeString, @MemberDeclListBuilder membersBuilder: () throws -> MemberDeclListSyntax) throws
 }
 
@@ -121,6 +149,19 @@ extension StructDeclSyntax: HasTrailingMemberDeclBlock {}
 // So we cannot conform to `HasTrailingCodeBlock`
 
 public extension IfExprSyntax {
+  /// Constructs an `if` expression with an optional `else` block.
+  ///
+  /// `header` specifies the part of the `if` expression before the body’s first brace. For example the following `if` expression has the header `if sunny`
+  ///
+  /// ```swift
+  /// if sunny {
+  ///   sunbath()
+  /// }
+  /// ```
+  ///
+  /// If `elseBuilder` is not `nil`, an `else` keyword will automatically be inserted.
+  ///
+  /// This function takes care of inserting the braces as well.
   init(_ header: PartialSyntaxNodeString, @CodeBlockItemListBuilder bodyBuilder: () throws -> CodeBlockItemListSyntax, @CodeBlockItemListBuilder `else` elseBuilder: () throws -> CodeBlockItemListSyntax? = { nil }) throws {
     let expr = ExprSyntax("\(header) {}")
     guard let ifExpr = expr.as(Self.self) else {
@@ -132,6 +173,30 @@ public extension IfExprSyntax {
     self.elseKeyword = elseBody != nil ? .keyword(.else) : nil
   }
 
+  /// Constructs an `if` expression with a following `else if` clause.
+  /// This can be used to create longer chains of `if`, `else if` expressions. For example to construct
+  ///
+  /// ```swift
+  /// if x == 1 {
+  ///     return "one
+  /// } else if x == 2 {
+  ///     return "two
+  /// } else {
+  ///     return "many
+  /// }
+  /// ```
+  ///
+  /// You can use
+  ///
+  /// ```swift
+  /// try IfExprSyntax("if x == 1", bodyBuilder: {
+  ///   StmtSyntax(#"return "one""#)
+  /// }, elseIf: IfExprSyntax("if x == 2", bodyBuilder: {
+  ///   StmtSyntax(#"return "two""#)
+  /// }, else: {
+  ///   StmtSyntax(#"return "many""#)
+  /// }))
+  /// ```
   init(_ header: PartialSyntaxNodeString, @CodeBlockItemListBuilder bodyBuilder: () throws -> CodeBlockItemListSyntax, elseIf: IfExprSyntax) throws {
     let expr = ExprSyntax("\(header) {}")
     guard let ifExpr = expr.as(Self.self) else {
@@ -147,6 +212,9 @@ public extension IfExprSyntax {
 // MARK: - SwitchCase
 
 extension SwitchCaseSyntax {
+  /// Constructs a case item where `header` includes the text between the `case` keyword and the `:` (both inclusive) and `statementsBuilder` can be used to build the statements inside the case item.
+  ///
+  /// For example, a `default` case has header `default:`.
   public init(_ header: PartialSyntaxNodeString, @CodeBlockItemListBuilder statementsBuilder: () throws -> CodeBlockItemListSyntax) rethrows {
     self = SwitchCaseSyntax("\(header)")
     self.statements = try statementsBuilder()
@@ -158,6 +226,18 @@ extension SwitchCaseSyntax {
 // So we cannot conform to `HasTrailingCodeBlock` or `HasTrailingMemberDeclBlock`
 
 public extension SwitchExprSyntax {
+  /// Constructs an `switch` expression where `header` builds the text before the opening `{` and `casesBuilder` can be used to build the case items.
+  ///
+  /// For example, the following switch expression hase header `switch direction` and two case items for `up` and `down`
+  ///
+  /// ```swift
+  /// switch direction {
+  /// case .up:
+  ///   goUp()
+  /// case .down:
+  ///   goDown()
+  /// }
+  /// ```
   init(_ header: PartialSyntaxNodeString, @SwitchCaseListBuilder casesBuilder: () throws -> SwitchCaseListSyntax = { SwitchCaseListSyntax([]) }) throws {
     let expr = ExprSyntax("\(header) {}")
     guard let switchExpr = expr.as(Self.self) else {

Tests/SwiftSyntaxBuilderTest/IfStmtTests.swift

@@ -97,6 +97,32 @@ final class IfStmtTests: XCTestCase {
         }
         """
       ),
+      #line: (
+        try IfExprSyntax(
+          "if x == 1",
+          bodyBuilder: {
+            StmtSyntax(#"return "one""#)
+          },
+          elseIf: IfExprSyntax(
+            "if x == 2",
+            bodyBuilder: {
+              StmtSyntax(#"return "two""#)
+            },
+            else: {
+              StmtSyntax(#"return "many""#)
+            }
+          )
+        ),
+        """
+        if x == 1 {
+            return "one"
+        } else if x == 2 {
+            return "two"
+        } else {
+            return "many"
+        }
+        """
+      ),
     ]
 
     for (line, testCase) in testCases {