Initial infrastructure for documenting SwiftSyntax API (swiftlang#14701)

Author: harlanhaskins

include/swift/Syntax/SyntaxNodes.h.gyb

@@ -49,6 +49,9 @@ using ${node.name} =
 % for node in SYNTAX_NODES:
 %   if not node.is_syntax_collection():
 %     qualifier = "" if node.is_base() else "final"
+%     for line in dedented_lines(node.description):
+/// ${line}
+%     end
 class ${node.name} ${qualifier} : public ${node.base_type} {
 %     if node.is_buildable():
       friend class ${node.name}Builder;
@@ -74,6 +77,9 @@ public:
     }
 
 %     for child in node.children:
+%       for line in dedented_lines(child.description):
+  /// ${line}
+%       end
 %       if child.is_optional:
   llvm::Optional<${child.type_name}> get${child.name}();
 %       else:
@@ -84,8 +90,18 @@ public:
 %       if child_node and child_node.is_syntax_collection():
 %         child_elt = child_node.collection_element_name
 %         child_elt_type = child_node.collection_element_type
+  /// Adds the provided `${child_elt}` to the node's `${child.name}`
+  /// collection.
+  /// - param element: The new `${child_elt}` to add to the node's
+  ///                  `${child.name}` collection.
+  /// - returns: A copy of the receiver with the provided `${child_elt}`
+  ///            appended to its `${child.name}` collection.
   ${node.name} add${child_elt}(${child_elt_type} ${child_elt});
 %       end
+
+  /// Returns a copy of the receiver with its `${child.name}` replaced.
+  /// - param newChild: The new `${child.name}` to replace the node's
+  ///                   current `${child.name}`, if present.
   ${node.name}
   with${child.name}(llvm::Optional<${child.type_name}> New${child.type_name});
 

tools/SwiftSyntax/SyntaxNodes.swift.gyb

@@ -57,11 +57,18 @@ public struct UnknownSyntax: _SyntaxBase {
 % for node in SYNTAX_NODES:
 %   base_type = node.base_type
 %   if node.is_base():
+%     for line in dedented_lines(node.description):
+/// ${line}
+%     end
 public protocol ${node.name}: Syntax {}
 
 %   elif node.collection_element:
 %     pass
 %   else:
+
+%     for line in dedented_lines(node.description):
+/// ${line}
+%     end
 public struct ${node.name}: ${base_type}, _SyntaxBase, Hashable {
 %     if node.children:
   enum Cursor: Int {
@@ -127,6 +134,9 @@ public struct ${node.name}: ${base_type}, _SyntaxBase, Hashable {
 %       end
 %       cast = '' if child.type_name == 'Syntax' \
 %                 else '%s %s' % (cast_symbol, child.type_name)
+%       for line in dedented_lines(child.description):
+  /// ${line}
+%       end
   public var ${child.swift_name}: ${ret_type} {
     let child = data.cachedChild(at: Cursor.${child.swift_name})
 %       if child.is_optional:
@@ -139,20 +149,29 @@ public struct ${node.name}: ${base_type}, _SyntaxBase, Hashable {
 %         child_elt = child_node.collection_element_name
 %         child_elt_type = child_node.collection_element_type
 
-  public func add${child_elt}(_ elt: ${child_elt_type}) -> ${node.name} {
+  /// Adds the provided `${child_elt}` to the node's `${child.swift_name}`
+  /// collection.
+  /// - param element: The new `${child_elt}` to add to the node's
+  ///                  `${child.swift_name}` collection.
+  /// - returns: A copy of the receiver with the provided `${child_elt}`
+  ///            appended to its `${child.swift_name}` collection.
+  public func add${child_elt}(_ element: ${child_elt_type}) -> ${node.name} {
     var collection: RawSyntax
     if let col = raw[Cursor.${child.swift_name}] {
-      collection = col.appending(elt.raw)
+      collection = col.appending(element.raw)
     } else {
       collection = RawSyntax.node(SyntaxKind.${child_node.swift_syntax_kind},
-                                  [elt.raw], .present)
+                                  [element.raw], .present)
     }
     let (root, newData) = data.replacingChild(collection,
                                               at: Cursor.${child.swift_name})
     return ${node.name}(root: root, data: newData)
   }
 %       end
 
+  /// Returns a copy of the receiver with its `${child.swift_name}` replaced.
+  /// - param newChild: The new `${child.swift_name}` to replace the node's
+  ///                   current `${child.swift_name}`, if present.
   public func with${child.name}(
     _ newChild: ${child.type_name}?) -> ${node.name} {
     let raw = newChild?.raw ?? ${make_missing_swift_child(child)}
@@ -162,10 +181,12 @@ public struct ${node.name}: ${base_type}, _SyntaxBase, Hashable {
   }
 %     end
 
+  /// Determines if two `${node.name}` nodes are equal to each other.
   public static func ==(lhs: ${node.name}, rhs: ${node.name}) -> Bool {
     return lhs._data === rhs._data
   }
 
+  /// A unique hash value for this node.
   public var hashValue: Int {
     return ObjectIdentifier(_data).hashValue
   }
@@ -202,6 +223,10 @@ extension ${node.name}: ${traits_list} {}
 /// MARK: Convenience methods
 
 extension StructDeclSyntax {
+  /// Creates a new StructDeclSyntax with the provided name as its identifier.
+  /// - param name: The new struct's name.
+  /// - returns: A new StructDeclSyntax with the same fields as the receiver,
+  ///            but with the provided identifier.
   func withIdentifier(_ name: String) -> StructDeclSyntax {
     let newToken = SyntaxFactory.makeIdentifier(name,
       leadingTrivia: identifier.leadingTrivia,

utils/gyb_syntax_support/Child.py

@@ -8,11 +8,12 @@ class Child(object):
     A child of a node, that may be declared optional or a token with a
     restricted subset of acceptable kinds or texts.
     """
-    def __init__(self, name, kind, is_optional=False,
+    def __init__(self, name, kind, description=None, is_optional=False,
                  token_choices=None, text_choices=None, node_choices=None):
         self.name = name
         self.swift_name = lowercase_first_word(name)
         self.syntax_kind = kind
+        self.description = description
         self.swift_syntax_kind = lowercase_first_word(self.syntax_kind)
         self.type_name = kind_to_type(self.syntax_kind)
 

utils/gyb_syntax_support/CommonNodes.py

@@ -15,14 +15,22 @@
 
     # code-block-item = (decl | stmt | expr) ';'?
     Node('CodeBlockItem', kind='Syntax',
+         description="""
+         A CodeBlockItem is any Syntax node that appears on its own line inside
+         a CodeBlock.
+         """,
          children=[
              Child('Item', kind='Syntax',
+                   description="The underlying node inside the code block.",
                    node_choices=[
                        Child('Decl', kind='Decl'),
                        Child('Stmt', kind='Stmt'),
                        Child('Expr', kind='Expr'),
                    ]),
              Child('Semicolon', kind='SemicolonToken',
+                   description="""
+                   If present, the trailing semicolon at the end of the item.
+                   """,
                    is_optional=True),
          ]),
 

utils/gyb_syntax_support/Node.py

@@ -16,11 +16,13 @@ class Node(object):
     subclass.
     """
 
-    def __init__(self, name, kind=None, traits=None, children=None,
-                 element=None, element_name=None, element_choices=None):
+    def __init__(self, name, description=None, kind=None, traits=None,
+                 children=None, element=None, element_name=None,
+                 element_choices=None):
         self.syntax_kind = name
         self.swift_syntax_kind = lowercase_first_word(name)
         self.name = kind_to_type(self.syntax_kind)
+        self.description = description
 
         self.traits = traits or []
         self.children = children or []

utils/gyb_syntax_support/Traits.py

@@ -2,9 +2,10 @@
 
 
 class Trait(object):
-    def __init__(self, trait_name, children):
+    def __init__(self, trait_name, description=None, children=None):
         self.trait_name = trait_name
         self.children = children
+        self.description = description
 
 
 TRAITS = [

utils/gyb_syntax_support/__init__.py

@@ -1,3 +1,4 @@
+import textwrap
 from AttributeNodes import ATTRIBUTE_NODES
 from CommonNodes import COMMON_NODES  # noqa: I201
 from DeclNodes import DECL_NODES  # noqa: I201
@@ -90,3 +91,12 @@ def create_node_map():
 
 def is_visitable(node):
     return not node.is_base() and not node.collection_element
+
+
+def dedented_lines(description):
+    """
+    Each line of the provided string with leading whitespace stripped.
+    """
+    if not description:
+        return []
+    return textwrap.dedent(description).split('\n')