Merge pull request #2179 from ahoppen/ahoppen/syntax-support-comments

Delete grammar comments in `CodeGeneration/SyntaxSupport` and translated all other comments to documentation

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/AttributeNodes.swift

@@ -11,7 +11,6 @@
 //===----------------------------------------------------------------------===//
 
 public let ATTRIBUTE_NODES: [Node] = [
-  // attribute-list -> attribute attribute-list?
   Node(
     kind: .attributeList,
     base: .syntaxCollection,
@@ -33,16 +32,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     elementChoices: [.attribute, .ifConfigDecl]
   ),
 
-  // attribute -> '@' identifier '('?
-  //              ( identifier
-  //                | string-literal
-  //                | integer-literal
-  //                | availability-spec-list
-  //                | specialize-attr-spec-list
-  //                | implements-attr-arguments
-  //                | named-attribute-string-argument
-  //                | back-deploy-attr-spec-list
-  //              )? ')'?
   Node(
     kind: .attribute,
     base: .syntax,
@@ -200,7 +189,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // back-deploy-version-entry -> availability-version-restriction ','?
   Node(
     kind: .platformVersionItem,
     base: .syntax,
@@ -222,17 +210,13 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // back-deploy-version-list ->
-  //   back-deploy-version-entry back-deploy-version-list?
   Node(
     kind: .platformVersionItemList,
     base: .syntaxCollection,
     nameForDiagnostics: "version list",
     elementChoices: [.platformVersionItem]
   ),
 
-  // The arguments of '@backDeployed(...)'
-  // back-deployed-attr-spec-list -> 'before' ':' back-deployed-version-list
   Node(
     kind: .backDeployedAttributeArguments,
     base: .syntax,
@@ -258,7 +242,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // convention-attribute-arguments -> token ',' 'cType'? ':' string-literal
   Node(
     kind: .conventionAttributeArguments,
     base: .syntax,
@@ -293,7 +276,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // convention-attribute-arguments -> 'witness_method' ':' identifier
   Node(
     kind: .conventionWitnessMethodAttributeArguments,
     base: .syntax,
@@ -315,12 +297,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // The argument of the derivative registration attribute
-  // '@derivative(of: ...)' and the transpose registration attribute
-  // '@transpose(of: ...)'.
-  //
-  // derivative-registration-attr-arguments ->
-  //     'of' ':' func-decl-name ','? differentiability-params-clause?
   Node(
     kind: .derivativeAttributeArguments,
     base: .syntax,
@@ -370,16 +346,13 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // differentiability-param-list ->
-  //     differentiability-param differentiability-param-list?
   Node(
     kind: .differentiabilityArgumentList,
     base: .syntaxCollection,
     nameForDiagnostics: "differentiability parameters",
     elementChoices: [.differentiabilityArgument]
   ),
 
-  // differentiability-param -> ('self' | identifier | integer-literal) ','?
   Node(
     kind: .differentiabilityArgument,
     base: .syntax,
@@ -402,8 +375,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // differentiability-params-clause ->
-  //     'wrt' ':' (differentiability-param | differentiability-params)
   Node(
     kind: .differentiabilityWithRespectToArgument,
     base: .syntax,
@@ -440,7 +411,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // differentiability-params -> '(' differentiability-param-list ')'
   Node(
     kind: .differentiabilityArguments,
     base: .syntax,
@@ -464,10 +434,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // The argument of '@differentiable(...)'.
-  // differentiable-attr-arguments ->
-  //     differentiability-kind? '.'? differentiability-params-clause? ','?
-  //     generic-where-clause?
   Node(
     kind: .differentiableAttributeArguments,
     base: .syntax,
@@ -541,7 +507,7 @@ public let ATTRIBUTE_NODES: [Node] = [
               .keyword(.public),
               .keyword(.open),
             ])
-          ),  // Keywords can be: public, internal, private, fileprivate, open
+          ),
           Child(
             name: "string",
             kind: .node(kind: .stringLiteralExpr)
@@ -618,9 +584,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // The argument of '@_implements(...)'
-  // implements-attr-arguments -> simple-type-identifier ','
-  //                              (identifier | operator) decl-name-arguments
   Node(
     kind: .implementsAttributeArguments,
     base: .syntax,
@@ -648,8 +611,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // Representation of e.g. 'exported: true,'
-  // labeled-specialize-entry -> identifier ':' token ','?
   Node(
     kind: .labeledSpecializeArgument,
     base: .syntax,
@@ -693,7 +654,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // objc-selector-piece -> identifier? ':'?
   Node(
     kind: .objCSelectorPiece,
     base: .syntax,
@@ -715,15 +675,13 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // objc-selector -> objc-selector-piece objc-selector?
   Node(
     kind: .objCSelectorPieceList,
     base: .syntaxCollection,
     nameForDiagnostics: "Objective-C selector",
     elementChoices: [.objCSelectorPiece]
   ),
 
-  // opaque-return-type-of-arguments -> string-literal ',' integer-literal
   Node(
     kind: .opaqueReturnTypeOfAttributeArguments,
     base: .syntax,
@@ -776,11 +734,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     ]
   ),
 
-  // The argument of '@_specialize(...)'
-  // specialize-attr-spec-list -> labeled-specialize-entry
-  //                                  specialize-spec-attr-list?
-  //                            | generic-where-clause
-  //                                  specialize-spec-attr-list?
   Node(
     kind: .specializeAttributeArgumentList,
     base: .syntaxCollection,
@@ -789,8 +742,6 @@ public let ATTRIBUTE_NODES: [Node] = [
     elementChoices: [.labeledSpecializeArgument, .specializeAvailabilityArgument, .specializeTargetFunctionArgument, .genericWhereClause]
   ),
 
-  // Representation of e.g. 'exported: true,'
-  // labeled-specialize-entry -> identifier ':' token ','?
   Node(
     kind: .specializeTargetFunctionArgument,
     base: .syntax,

CodeGeneration/Sources/SyntaxSupport/AvailabilityNodes.swift

@@ -11,11 +11,6 @@
 //===----------------------------------------------------------------------===//
 
 public let AVAILABILITY_NODES: [Node] = [
-  // Wrapper for all the different entries that may occur inside @available
-  // availability-entry -> '*' ','?
-  //                     | identifier ','?
-  //                     | availability-version-restriction ','?
-  //                     | availability-versioned-argument ','?
   Node(
     kind: .availabilityArgument,
     base: .syntax,
@@ -55,8 +50,6 @@ public let AVAILABILITY_NODES: [Node] = [
     ]
   ),
 
-  // Representation of 'deprecated: 2.3', 'message: "Hello world"' etc.
-  // availability-versioned-argument -> identifier ':' version-tuple
   Node(
     kind: .availabilityLabeledArgument,
     base: .syntax,
@@ -98,16 +91,13 @@ public let AVAILABILITY_NODES: [Node] = [
     ]
   ),
 
-  // availability-spec-list -> availability-entry availability-spec-list?
   Node(
     kind: .availabilityArgumentList,
     base: .syntaxCollection,
     nameForDiagnostics: "'@availability' arguments",
     elementChoices: [.availabilityArgument]
   ),
 
-  // Representation for 'iOS 10', 'swift 3.4' etc.
-  // availability-version-restriction -> identifier version-tuple
   Node(
     kind: .platformVersion,
     base: .syntax,
@@ -137,7 +127,6 @@ public let AVAILABILITY_NODES: [Node] = [
     ]
   ),
 
-  // version-tuple-element -> '.' integer-literal
   Node(
     kind: .versionComponent,
     base: .syntax,
@@ -157,15 +146,13 @@ public let AVAILABILITY_NODES: [Node] = [
     ]
   ),
 
-  // version-list -> version-tuple-element version-list?
   Node(
     kind: .versionComponentList,
     base: .syntaxCollection,
     nameForDiagnostics: nil,
     elementChoices: [.versionComponent]
   ),
 
-  // version-tuple -> integer-literal version-list?
   Node(
     kind: .versionTuple,
     base: .syntax,

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -11,15 +11,13 @@
 //===----------------------------------------------------------------------===//
 
 public let COMMON_NODES: [Node] = [
-  // code-block-item-list -> code-block-item code-block-item-list?
   Node(
     kind: .codeBlockItemList,
     base: .syntaxCollection,
     nameForDiagnostics: nil,
     elementChoices: [.codeBlockItem]
   ),
 
-  // code-block-item = (decl | stmt | expr) ';'?
   Node(
     kind: .codeBlockItem,
     base: .syntax,
@@ -54,7 +52,6 @@ public let COMMON_NODES: [Node] = [
     ]
   ),
 
-  // code-block -> '{' stmt-list '}'
   Node(
     kind: .codeBlock,
     base: .syntax,
@@ -80,7 +77,6 @@ public let COMMON_NODES: [Node] = [
     ]
   ),
 
-  // accessor-effect-specifiers -> (async)? (throws)?
   Node(
     kind: .accessorEffectSpecifiers,
     base: .syntax,
@@ -102,7 +98,6 @@ public let COMMON_NODES: [Node] = [
     ]
   ),
 
-  // funtion-effect-specifiers -> (async | reasync)? (throws | rethrows)?
   Node(
     kind: .functionEffectSpecifiers,
     base: .syntax,
@@ -124,7 +119,6 @@ public let COMMON_NODES: [Node] = [
     ]
   ),
 
-  // deinit-effect-specifiers -> async?
   Node(
     kind: .deinitializerEffectSpecifiers,
     base: .syntax,
@@ -305,7 +299,6 @@ public let COMMON_NODES: [Node] = [
     parserFunction: "parseStatement"
   ),
 
-  // type-effect-specifiers -> async? throws?
   Node(
     kind: .typeEffectSpecifiers,
     base: .syntax,