Merge pull request #1777 from ahoppen/ahoppen/docc-warnings

Fix warnings when generating documentation using docc

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

@@ -634,7 +634,7 @@ public let DECL_NODES: [Node] = [
       Child(
         name: "Attributes",
         kind: .collection(kind: .attributeList, collectionElementName: "Attribute"),
-        documentation: "If there were attributes before the editor placeholder, the ``EditorPlaceholderDecl`` will contain these.",
+        documentation: "If there were attributes before the editor placeholder, the ``EditorPlaceholderDeclSyntax`` will contain these.",
         isOptional: true
       ),
       Child(

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift

@@ -46,7 +46,6 @@ let nodesSections: String = {
     types: [
       "SyntaxChildren",
       "SyntaxChildrenIndex",
-      "SyntaxChildrenIndexData",
     ]
       + SYNTAX_NODES.flatMap({ (node: Node) -> [String] in
         guard let node = node.collectionNode else {
@@ -62,7 +61,7 @@ let nodesSections: String = {
 
   addSection(heading: "Miscellaneous Syntax", types: SYNTAX_NODES.map(\.kind.syntaxType.description).filter({ !handledSyntaxTypes.contains($0) }))
 
-  addSection(heading: "Traits", types: TRAITS.map(\.traitName))
+  addSection(heading: "Traits", types: TRAITS.map { "\($0.traitName)Syntax" })
 
   return result
 }()

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md

@@ -82,4 +82,3 @@ These articles are intended for developers wishing to contribute to SwiftSyntax
 - <doc:SwiftSyntax/SyntaxEnum>
 - <doc:SwiftSyntax/SyntaxHashable>
 - <doc:SwiftSyntax/SyntaxIdentifier>
-- <doc:SwiftSyntax/RawTokenKind>

Sources/SwiftParser/Parser.swift

@@ -29,8 +29,8 @@
 /// from a bad parse should be left `nonmutating` to indicate that they do not
 /// consume tokens.
 ///
-/// Token consumption is generally either unconditional via ``TokenConsumer/consumeAnyToken()``
-/// or conditional via a combination of ``TokenConsumer/at(_:where:)``
+/// Token consumption is generally either unconditional via `TokenConsumer.consumeAnyToken()`
+/// or conditional via a combination of `TokenConsumer/at(_:where:)`
 /// and `TokenConsumer.eat(_:)`. When parsing conditionally, `at` returns a
 /// handle that is passed to `eat`. This ensures that any structure that is
 /// checked for is actually parsed by the parser at that position. If the parser
@@ -46,7 +46,7 @@
 ///     /*  */
 ///     let rbrace = self.expect(.rightBrace)
 ///
-/// Unlike ``TokenConsumer/eat(_:)``, ``Parser/expect(_:remapping:)`` returns
+/// Unlike `TokenConsumer.eat(_:)`, `Parser.expect(_:remapping:)` returns
 /// a `missing` token of the given kind. This allows the tree to remain
 /// well-formed even when the input text is not, all without affecting
 /// source fidelity.
@@ -72,8 +72,8 @@
 ///
 /// This parser provides at most one token worth of lookahead via
 /// `peek()`. If more tokens are required to disambiguate a parse, a
-/// ``Parser/Lookahead`` instance should be constructed instead with
-/// ``Parser/lookahead()``.
+/// `Parser.Lookahead` instance should be constructed instead with
+/// `Parser.lookahead()`.
 ///
 /// Source Fidelity
 /// ===============

Sources/SwiftParser/SwiftParser.docc/FixingBugs.md

@@ -65,8 +65,8 @@ To add a new, more contextual diagnostic, perform the following steps.
     ```
 2. Mark the location at which you expect the diagnostic to be produced with `1️⃣`. If you expect multiple diagnostics to be produced, you can use multiple of these markers with different names and use these markers by passing a `locationMarker` to `DiagnosticSpec`. The list of valid marker emojis can be found in `Character.isMarkerEmoji`.
 3. Determine which node encompasses all information that is necessary to produce the improved diagnostic – for example `FunctionSignatureSyntax` contains all information to diagnose if the `throws` keyword was written after the `->` instead of in front of it.
-4. If the diagnostic message you want to emit does not exist yet, add a case to <doc:SwiftParser/DiagnosticKind> for the new diagnostic.
-5. If the function does not already exist, write a new visit method on <doc:SwiftParser/ParseDiagnosticsGenerator>.
+4. If the diagnostic message you want to emit does not exist yet, add a case to `StaticParserError` for the new diagnostic. If the diagnostic needs to take parameters, add a new struct to in `ParserDiagnsoticMessages.swift`.
+5. If the function does not already exist, write a new visit method on `ParseDiagnosticsGenerator`.
 6. In that visitation method, detect the pattern for which the improved diagnostic should be emitted and emit it using `diagnostics.append`.
 7. Mark the missing or garbage nodes that are covered by the new diagnostic as handled by adding their `SyntaxIdentifier`s to `handledNodes`.
 8. If the diagnostic produces Fix-Its assert that they are generated by adding the Fix-It's message to the `DiagnosticSpec` with the `fixIt` parameter and asserting that applying the Fix-Its produces the correct source code by adding the `fixedSource` parameter to `assertParse`.

Sources/SwiftParser/SwiftParser.docc/ParserDesign.md

@@ -109,8 +109,8 @@ stateless. It is not a hard and fast rule that the parse be stateless, but
 engineering it with that mindset has enabled a relatively clean, testable 
 parser design to emerge. Swift is not a context-free language, so there will
 inevitably need to be some state involved during the parse. The parser is
-designed to sequester those stateful decisions 
-(e.g. <doc:SwiftParser/Parser/Lookahead>) away from the main parse productions.
+designed to sequester those stateful decisions (e.g. `Parser.Lookahead`) 
+away from the main parse productions.
 
 What ambient state is present occurs as arguments to certain productions that
 are required to enable or disable their child productions in response to some 

Sources/SwiftParser/SwiftParser.docc/ParserRecovery.md

@@ -33,7 +33,7 @@ with these diagnostics.
 
 When the parser expects a token but can’t find it, it looks ahead to see if it 
 can find the expected token by using a token precedence model. Tokens are 
-divided in precedence groups (see ``TokenPrecedence``), 
+divided in precedence groups (see `TokenPrecedence`), 
 dependening on how strongly they mark the structure of the source code. For 
 example, keywords that start a declaration, like `func`, have a higher 
 precedence than expression keywords, like `self`.

Sources/SwiftParser/SwiftParser.docc/ParsingBasics.md

@@ -108,15 +108,15 @@ extension Parser {
 ```
 
 This simple function introduces many of the basic concepts that form the
-backbone of the parser's implementation. The ``Parser/eat(_:)`` method
+backbone of the parser's implementation. The `Parser.eat(_:)` method
 provides a function to examine the input stream and advance one step if the
 provided token kind is present. To form the node, a call to the initializer
 is made, which acts to wire up all of the sub-nodes into a single 
 `RawOptionalTypeSyntax`.
 
 ### Unconditional Parsing
 
-The ``Parser/eat(_:)`` method unconditionally consumes a token of the given
+The `Parser.eat(_:)` method unconditionally consumes a token of the given
 type, and an assertion is raised if the input token's kind does not match.
 This function is most appropriate for encoding structural invariants during
 the parse. For example, the decision to parse a `FunctionDeclSyntax` node is
@@ -128,7 +128,7 @@ calling the function parsing method.
 ### Conditional Parsing
 
 To model conditional productions, the syntax tree uses `Optional`-typed
-syntax nodes, and the parser uses the ``Parser/consume(if:)`` method. 
+syntax nodes, and the parser uses the `Parser.consume(if:)` method. 
 For a Swift declaration item, a trailing semicolon is optional:
 
 ```swift
@@ -146,7 +146,7 @@ extension Parser {
 }
 ```
 
-Unlike ``Parser/eat(_:)``, if the parser does not encounter a token of the
+Unlike `Parser.eat(_:)`, if the parser does not encounter a token of the
 given type, a `nil` token is returned and the input is left unconsumed.
 
 ### Sequence Parsing

Sources/SwiftParser/SwiftParser.docc/SwiftParser.md

@@ -46,19 +46,6 @@ There are several design principles that govern the parser:
 - **Minimal context**: The parser requires minimal context to parse Swift code, which consists of only those things required to handle a suitable Swift dialect, e.g., whether [regex literals](https://github.com/apple/swift-evolution/blob/main/proposals/0354-regex-literals.md) are supported. The parser can be invoked on any input source code, starting at any major production in the grammar (e.g., full source file, an individual type, an individual expression).
 - **Incremental**: A parse tree produced for a source file can be incrementally updated for a new version of that source file, reusing syntax nodes where possible to reduce computation overhead and memory.
 
-### Lexical Analysis
-
-- <doc:SwiftParser/Lexer>
-- <doc:SwiftParser/Lexer/Lexeme>
-- <doc:SwiftParser/Lexer/Cursor>
-- <doc:SwiftParser/Lexer/LexemeSequence>
-
-### Parsing
-
-- <doc:SwiftParser/TokenConsumer>
-- <doc:SwiftParser/Parser>
-- <doc:SwiftParser/Parser/Lookahead>
-
 ### Development
 
 - <doc:SwiftParser/FilingBugReports>

Sources/SwiftSyntax/Documentation.docc/Contributing/SPI.md

@@ -2,8 +2,8 @@
 
 Learn when SwiftSyntax exposes declaration annotated as `@_spi`.
 
-Functions marked as `@_spi(RawSyntax)` (where ``RawSyntax`` can be any name) are considered *SPI* (System Programming Interface) and are only accessible if the module that declares them is imported as `@_spi(RawSyntax)`.
+Functions marked as `@_spi(RawSyntax)` (where `RawSyntax` can be any name) are considered *SPI* (System Programming Interface) and are only accessible if the module that declares them is imported as `@_spi(RawSyntax)`.
 
 Since functions marked as SPI are not part of the public API, swift-syntax makes no guarantee to their source stability. swift-syntax makes no effort to keep its SPI stable.
 
-Declarations are typically marked as SPI because they have some kind of caveat that makes them unsafe to use in general. For example, when accessing ``RawSyntax`` nodes, you need to manually guarantee that the ``SyntaxArena`` they’re allocated in will not be de-allocated. Other declarations have an `@_spi` to share them between different modules within the swift-syntax package. These would use the [`package` modifier](https://github.com/apple/swift-evolution/blob/main/proposals/0386-package-access-modifier.md) if not for the fact that swift-syntax needed to compile with the last two Swift releases (see <doc:Swift-Version>).
+Declarations are typically marked as SPI because they have some kind of caveat that makes them unsafe to use in general. For example, when accessing `RawSyntax` nodes, you need to manually guarantee that the ``SyntaxArena`` they’re allocated in will not be de-allocated. Other declarations have an `@_spi` to share them between different modules within the swift-syntax package. These would use the [`package` modifier](https://github.com/apple/swift-evolution/blob/main/proposals/0386-package-access-modifier.md) if not for the fact that swift-syntax needed to compile with the last two Swift releases (see <doc:Swift-Version>).