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>).

Sources/SwiftSyntax/Documentation.docc/Working with SwiftSyntax.md

@@ -178,7 +178,7 @@ of high-level APIs for expressing these modifications. In general, data in
 syntax nodes can be accessed via a getter and updated with a corresponding
 `with*` method. For example, the name of a class can be retrieved with the
 ``ClassDeclSyntax/identifier`` accessor, and replaced with the 
-``ClassDeclSyntax/withIdentifier(_:)`` update function. This method returns
+``ClassDeclSyntax/with(_:_:)-3exln`` update function. This method returns
 a new ``ClassDeclSyntax`` value.
 
 ## Building Syntax Trees

Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md

@@ -203,7 +203,6 @@ These articles are intended for developers wishing to contribute to SwiftSyntax
 
 - <doc:SwiftSyntax/SyntaxChildren>
 - <doc:SwiftSyntax/SyntaxChildrenIndex>
-- <doc:SwiftSyntax/SyntaxChildrenIndexData>
 - <doc:SwiftSyntax/AccessorListSyntax>
 - <doc:SwiftSyntax/ArrayElementListSyntax>
 - <doc:SwiftSyntax/ArrayElementSyntax>
@@ -371,17 +370,17 @@ These articles are intended for developers wishing to contribute to SwiftSyntax
 
 ### Traits
 
-- <doc:SwiftSyntax/Braced>
-- <doc:SwiftSyntax/DeclGroup>
-- <doc:SwiftSyntax/EffectSpecifiers>
-- <doc:SwiftSyntax/FreestandingMacroExpansion>
-- <doc:SwiftSyntax/IdentifiedDecl>
-- <doc:SwiftSyntax/Parenthesized>
-- <doc:SwiftSyntax/WithAttributes>
-- <doc:SwiftSyntax/WithCodeBlock>
-- <doc:SwiftSyntax/WithModifiers>
-- <doc:SwiftSyntax/WithStatements>
-- <doc:SwiftSyntax/WithTrailingComma>
+- <doc:SwiftSyntax/BracedSyntax>
+- <doc:SwiftSyntax/DeclGroupSyntax>
+- <doc:SwiftSyntax/EffectSpecifiersSyntax>
+- <doc:SwiftSyntax/FreestandingMacroExpansionSyntax>
+- <doc:SwiftSyntax/IdentifiedDeclSyntax>
+- <doc:SwiftSyntax/ParenthesizedSyntax>
+- <doc:SwiftSyntax/WithAttributesSyntax>
+- <doc:SwiftSyntax/WithCodeBlockSyntax>
+- <doc:SwiftSyntax/WithModifiersSyntax>
+- <doc:SwiftSyntax/WithStatementsSyntax>
+- <doc:SwiftSyntax/WithTrailingCommaSyntax>
 
 
 
@@ -410,4 +409,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/SwiftSyntax/SyntaxArena.swift

@@ -13,7 +13,7 @@
 /// A syntax arena owns the memory for all syntax nodes within it.
 ///
 /// The following is only relevant if you are accessing the raw syntax tree using
-/// ``RawSyntax`` nodes. When working with syntax trees using SwiftSyntax’s API,
+/// `RawSyntax` nodes. When working with syntax trees using SwiftSyntax’s API,
 /// the usage of a ``SyntaxArena`` is transparent.
 ///
 /// Contrary to Swift’s usual memory model, syntax node's are not individually
@@ -26,15 +26,15 @@
 /// As a consequence, syntax nodes cannot be freed individually but the memory
 /// will get freed once the owning ``SyntaxArena`` gets freed. Thus, it needs to
 /// be manually ensured that the ``SyntaxArena`` is not deallocated while any
-/// of its nodes are being accessed. The ``SyntaxData`` type ensures this as
+/// of its nodes are being accessed. The `SyntaxData` type ensures this as
 /// follows:
 /// - The root node has a strong reference to its ``SyntaxArena``
-/// - Each node retains its parent ``SyntaxData``, thus keeping it alive.
+/// - Each node retains its parent `SyntaxData`, thus keeping it alive.
 /// - If any node is allocated within a different ``SyntaxArena``,  that arena
 ///   is added to the root's `childRefs` property and thus kept a live as long
 ///   as the parent tree is alive.
 ///
-/// As an added benefit of the ``SyntaxArena``, ``RawSyntax`` nodes don’t need to
+/// As an added benefit of the ``SyntaxArena``, `RawSyntax` nodes don’t need to
 /// be reference-counted, further improving the performance of ``SwiftSyntax``
 /// when worked with at that level.
 public class SyntaxArena {

Sources/SwiftSyntax/TokenSyntax.swift

@@ -139,7 +139,7 @@ public struct TokenSyntax: SyntaxProtocol, SyntaxHashable {
   /// empty layout node.
   ///
   /// Every syntax node that contains a token will have a
-  /// ``SyntaxNodeStructure.SyntaxChoices.choices`` case for the token and those
+  /// ``SyntaxNodeStructure/SyntaxChoice/token(_:)`` case for the token and those
   /// choices represent the token kinds the token might have.
   public static var structure: SyntaxNodeStructure {
     return .layout([])

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxDeclNodes.swift

@@ -1528,7 +1528,7 @@ public struct EditorPlaceholderDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// If there were attributes before the editor placeholder, the ``EditorPlaceholderDecl`` will contain these.
+  /// If there were attributes before the editor placeholder, the ``EditorPlaceholderDeclSyntax`` will contain these.
   public var attributes: AttributeListSyntax? {
     get {
       return data.child(at: 1, parent: Syntax(self)).map(AttributeListSyntax.init)

Sources/SwiftSyntaxBuilder/ConvenienceInitializers.swift

@@ -43,7 +43,7 @@ extension ArrayExprSyntax {
 extension AttributeSyntax {
   /// A convenience initializer that allows passing in arguments using a result builder
   /// and automatically adds parentheses as needed, similar to the convenience
-  /// initializer for ``FunctionCallExpr``.
+  /// initializer for ``FunctionCallExprSyntax``.
   public init(
     _ attributeName: TypeSyntax,
     @TupleExprElementListBuilder argumentList: () -> TupleExprElementListSyntax? = { nil }

Sources/SwiftSyntaxBuilder/Syntax+StringInterpolation.swift

@@ -106,7 +106,7 @@ extension SyntaxStringInterpolation: StringInterpolationProtocol {
 
   /// Interpolates a literal or similar expression syntax equivalent to `value`.
   ///
-  /// - SeeAlso: ``Expr/init(literal:)``
+  /// - SeeAlso: ``SwiftSyntax/ExprSyntax/init(literal:)``
   public mutating func appendInterpolation(
     literal value: some ExpressibleByLiteralSyntax,
     format: BasicFormat = BasicFormat()
@@ -118,7 +118,7 @@ extension SyntaxStringInterpolation: StringInterpolationProtocol {
   // it silences a warning about interpolating Optionals.
   /// Interpolates a literal or similar expression syntax equivalent to `value`.
   ///
-  /// - SeeAlso: ``Expr/init(literal:)``
+  /// - SeeAlso: ``SwiftSyntax/ExprSyntax/init(literal:)``
   public mutating func appendInterpolation<Literal: ExpressibleByLiteralSyntax>(
     literal value: Literal?,
     format: BasicFormat = BasicFormat()
@@ -161,10 +161,10 @@ enum SyntaxStringInterpolationError: Error, CustomStringConvertible {
 /// Conforming types do not *contain* Swift source code; rather, they can be
 /// *expressed* in Swift source code, and this protocol can be used to get
 /// whatever source code would do that. For example, `String` is
-/// `ExpressibleByLiteralSyntax` but ``StringLiteralExprSyntax`` is not.
+/// `ExpressibleByLiteralSyntax` but ``SwiftSyntax/StringLiteralExprSyntax`` is not.
 ///
 /// This protocol is usually not used directly. Instead, conforming types can
-/// be turned into syntax trees using ``Expr/init(literal:)``:
+/// be turned into syntax trees using ``SwiftSyntax/ExprSyntax/init(literal:)``:
 ///
 ///     let expr2 = Expr(literal: [0+1, 1+1, 2+1])
 ///     // `expr2` is a syntax tree for `[1, 2, 3]`.
@@ -195,7 +195,7 @@ public protocol ExpressibleByLiteralSyntax {
   /// Returns a syntax tree that represents the value of this instance.
   ///
   /// This method is usually not called directly. Instead, conforming types can
-  /// be turned into syntax trees using ``Expr/init(literal:)``:
+  /// be turned into syntax trees using ``SwiftSyntax/ExprSyntax/init(literal:)``:
   ///
   ///     let expr2 = Expr(literal: [0+1, 1+1, 2+1])
   ///     // `expr2` is a syntax tree for `[1, 2, 3]`.