Add some more documentaiton on assertParse

Author: ahoppen

Sources/SwiftSyntax/generated/raw/RawSyntaxValidation.swift

@@ -184,6 +184,8 @@ func validateLayout(layout: RawSyntaxBuffer, as kind: SyntaxKind) {
       assertionFailure("""
         Error validating child at index \(index) of \(nodeKind):
         \(error.description)
+
+        See "RawSyntax Validation" in CONTRIBUTING.md to reproduce the fialure locally.
         """, file: file, line: line)
     }
   }
@@ -198,6 +200,8 @@ func validateLayout(layout: RawSyntaxBuffer, as kind: SyntaxKind) {
         Node did not satisfy any node choice requirement.
         Validation failures:
         \(nonNilErrors.map({ "- \($0.description)" }).joined(separator: "\n"))
+
+        See "RawSyntax Validation" in CONTRIBUTING.md to reproduce the fialure locally.
         """, file: file, line: line)
       _ = 1
     }

Tests/SwiftParserTest/Assertions.swift

@@ -233,7 +233,7 @@ struct NoteSpec {
 
 /// An abstract data structure to describe how a diagnostic produced by the parser should look like.
 struct DiagnosticSpec {
-  /// The name of a maker (of the form `1️⃣`) in the source code that marks the location where the diagnostis should be produced.
+  /// The name of a maker (of the form `1️⃣`) in the source code that marks the location where the diagnostic should be produced.
   let locationMarker: String
   /// If not `nil`, assert that the diagnostic has the given ID.
   let id: MessageID?
@@ -531,7 +531,7 @@ public struct AssertParseOptions: OptionSet {
 extension ParserTestCase {
   /// After a test case has been mutated, assert that the mutated source
   /// round-trips and doesn’t hit any assertion failures in the parser.
-  fileprivate func assertRoundTrip<S: SyntaxProtocol>(
+  fileprivate func assertMutatedSourceRoundTrips<S: SyntaxProtocol>(
     source: [UInt8],
     _ parse: (inout Parser) -> S,
     experimentalFeatures: Parser.ExperimentalFeatures,
@@ -564,23 +564,42 @@ extension ParserTestCase {
     }
   }
 
-  /// Removes any test markers from `markedSource` (1) and parses the result
-  /// using `parse`. By default it only checks if the parsed syntax tree is
-  /// printable back to the origin source, ie. it round trips.
+  /// Verifies that parsing of `markedSource` produces expected results using a
+  /// combination of various testing techniques:
+  ///
+  /// 1. Asserts that parsing of `markedSource` round-trips, ie. that the printed
+  ///    parsed tree is the same as the input.
+  /// 2. Checks that parsing produces the expected list of diagnostics. If no
+  ///    diagnostics are passed, asserts that the input parses without any errors.
+  /// 3. Checks that applying all Fix-Its of the source code results in the
+  ///    expected fixed source, effectively testing the Fix-Its.
+  /// 4. If a substructure is passed, asserts that the parsed tree contains a
+  ///    subtree of that structure.
+  /// 5. Mutates the test input by flipping each token's presence (ie. for every
+  ///    token, remove it from the input if it is present in the parsed tree and
+  ///    synthesize a missing tokens into the input) and verifies that this
+  ///    mutated input round-trips. This test is disabled if the
+  ///    `SKIP_LONG_TESTS` environment variable is set.
+  /// 6. If swift-syntax is compiled with the
+  ///    `SWIFTPARSER_ENABLE_ALTERNATE_TOKEN_INTROSPECTION` environment variable
+  ///    set, mutates the input based on tokens the parse is trying to parse.
+  ///    See the *Test Case Mutation* section in CONTRIBUTING.md.
   ///
-  /// (1) `markedSource` is source that can include markers of the form `1️⃣`,
-  /// to be used as locations in the following parameters when they exist.
   ///
   /// - Parameters:
-  ///   - substructure: Asserts the parsed syntax tree contains this structure.
+  ///   - markedSource: source that can include markers of the form `1️⃣`,
+  ///     to be used as locations in the following parameters.
+  ///   - parse: The function with which the source code should be parsed.
+  ///     Defaults to parsing as a source file.
+  ///   - expectedSubstructure: Asserts the parsed syntax tree contains this structure.
   ///   - substructureAfterMarker: Changes the position to start the structure
   ///     assertion from, ie. allows matching a particular substructure rather
   ///     than the whole source.
-  ///   - diagnostics: Asserts the given diagnostics were output, by default it
+  ///   - expectedDiagnostics: Asserts the given diagnostics were output, by default it
   ///     asserts the parse was successful (ie. it has no diagnostics). Note
   ///     that `DiagnosticsSpec` uses the location marked by `1️⃣` by default.
   ///   - applyFixIts: Applies only the fix-its with these messages.
-  ///   - fixedSource: Asserts that the source after applying fix-its matches
+  ///   - expectedFixedSource: Asserts that the source after applying fix-its matches
   ///     this string.
   ///   - experimentalFeatures: A list of experimental features to enable, or
   ///     `nil` to enable the default set of features provided by the test case.
@@ -693,7 +712,7 @@ extension ParserTestCase {
       DispatchQueue.concurrentPerform(iterations: Array(tree.tokens(viewMode: .all)).count) { tokenIndex in
         let flippedTokenTree = TokenPresenceFlipper(flipTokenAtIndex: tokenIndex).rewrite(Syntax(tree))
         _ = ParseDiagnosticsGenerator.diagnostics(for: flippedTokenTree)
-        assertRoundTrip(source: flippedTokenTree.syntaxTextBytes, parse, experimentalFeatures: experimentalFeatures, file: file, line: line)
+        assertMutatedSourceRoundTrips(source: flippedTokenTree.syntaxTextBytes, parse, experimentalFeatures: experimentalFeatures, file: file, line: line)
       }
 
       #if SWIFTPARSER_ENABLE_ALTERNATE_TOKEN_INTROSPECTION
@@ -703,7 +722,7 @@ extension ParserTestCase {
       DispatchQueue.concurrentPerform(iterations: mutations.count) { index in
         let mutation = mutations[index]
         let alternateSource = MutatedTreePrinter.print(tree: Syntax(tree), mutations: [mutation.offset: mutation.replacement])
-        assertRoundTrip(source: alternateSource, parse, experimentalFeatures: experimentalFeatures, file: file, line: line)
+        assertMutatedSourceRoundTrips(source: alternateSource, parse, experimentalFeatures: experimentalFeatures, file: file, line: line)
       }
       #endif
     }