Merge pull request #1701 from ahoppen/ahoppen/doc-improvements

Improve doc comments based on review comments

Author: ahoppen

Sources/SwiftParserDiagnostics/LexerDiagnosticMessages.swift

@@ -204,8 +204,8 @@ public extension SwiftSyntax.TokenDiagnostic {
       }
       let replacedText =
         text
-        .replacingFirstOccurence(of: "“", with: #"""#)
-        .replacingLastOccurence(of: "”", with: #"""#)
+        .replacingFirstOccurrence(of: "“", with: #"""#)
+        .replacingLastOccurrence(of: "”", with: #"""#)
 
       let fixedToken = token.with(\.tokenKind, TokenKind.fromRaw(kind: rawKind, text: replacedText))
       return [

Sources/SwiftParserDiagnostics/Utils.swift

@@ -13,7 +13,7 @@
 extension String {
   /// Returns this string with the first letter uppercased.
   ///
-  /// If thes string does not start with a letter, no change is made to it.
+  /// If the string does not start with a letter, no change is made to it.
   func withFirstLetterUppercased() -> String {
     if let firstLetter = self.first {
       return firstLetter.uppercased() + self.dropFirst()
@@ -22,20 +22,20 @@ extension String {
     }
   }
 
-  /// Replace the first occurance of `character` with `replacement`.
+  /// Replace the first occurrence of `character` with `replacement`.
   ///
   /// If `character` does not occur in this string, no change is made.
-  func replacingFirstOccurence(of character: Character, with replacement: Character) -> String {
+  func replacingFirstOccurrence(of character: Character, with replacement: Character) -> String {
     guard let match = self.firstIndex(of: character) else {
       return self
     }
     return self[startIndex..<match] + String(replacement) + self[index(after: match)...]
   }
 
-  /// Replace the last occurance of `character` with `replacement`.
+  /// Replace the last occurrence of `character` with `replacement`.
   ///
   /// If `character` does not occur in this string, no change is made.
-  func replacingLastOccurence(of character: Character, with replacement: Character) -> String {
+  func replacingLastOccurrence(of character: Character, with replacement: Character) -> String {
     guard let match = self.lastIndex(of: character) else {
       return self
     }

Sources/SwiftSyntax/BumpPtrAllocator.swift

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A `BumpPtrAllocator` that allocates `slabSize` at a time.
+/// A ``BumpPtrAllocator`` that allocates `slabSize` at a time.
 /// Once all memory in a slab has been used, it allocates a new slab and no
 /// memory allocations are necessary until that slab is completely filled up.
 @_spi(RawSyntax) @_spi(Testing)
@@ -37,9 +37,7 @@ public class BumpPtrAllocator {
   private var customSizeSlabs: [Slab]
   private var _totalBytesAllocated: Int
 
-  /// Construct a new ``BumpPtrAllocator`` that allocates `slabSize` at a time.
-  /// Once all memory in a slab has been used, it allocates a new slab and no
-  /// memory allocations are necessary until that slab is completely filled up.
+  /// Construct a new ``BumpPtrAllocator``.
   public init(slabSize: Int) {
     self.slabSize = slabSize
     slabs = []

Sources/SwiftSyntax/SourceLocation.swift

@@ -55,20 +55,22 @@ public struct SourceLocation: Hashable, Codable, CustomDebugStringConvertible {
   }
 }
 
-/// Represents a start and end location in a Swift file.
+/// Represents a half-open range in a Swift file.
 public struct SourceRange: Hashable, Codable, CustomDebugStringConvertible {
 
-  /// The beginning location in the source range.
+  /// The beginning location of the source range.
   ///
   /// This location is included in the range
   public let start: SourceLocation
 
-  /// The beginning location in the source range.
+  /// The end location of the source range.
   ///
-  /// This location is no longer part of the range
+  /// The location of the character after the end of the range,
+  /// ie. this location is not included in the range.
   public let end: SourceLocation
 
-  /// A description describing this range for debugging purposes, don't rely on it.
+  /// A description describing this range for debugging purposes, don't rely on
+  /// it being stable
   public var debugDescription: String {
     return "(\(start.debugDescription),\(end.debugDescription))"
   }

Sources/SwiftSyntax/Syntax.swift

@@ -59,7 +59,7 @@ public struct Syntax: SyntaxProtocol, SyntaxHashable {
 
   /// Needed for the conformance to ``SyntaxProtocol``.
   ///
-  /// Kind of non-sensical on `Syntax` since this just returns `self`.
+  /// Needed for the conformance to ``SyntaxProtocol``. Just returns `self`.
   public var _syntaxNode: Syntax {
     return self
   }
@@ -73,12 +73,12 @@ public struct Syntax: SyntaxProtocol, SyntaxHashable {
     self.init(.forRoot(raw))
   }
 
-  /// Create a `Syntax` node from a specialized syntax node.
+  /// Create a ``Syntax`` node from a specialized syntax node.
   public init(_ syntax: some SyntaxProtocol) {
     self = syntax._syntaxNode
   }
 
-  /// Creates a new `Syntax` node from any concrete node that conforms to `SyntaxProtocol`.
+  /// Creates a new `Syntax` node from any node that conforms to ``SyntaxProtocol``.
   public init(fromProtocol syntax: SyntaxProtocol) {
     self = syntax._syntaxNode
   }
@@ -111,14 +111,7 @@ public struct Syntax: SyntaxProtocol, SyntaxHashable {
   /// Returns `true` if `rhs` and `lhs` have the same ID.
   ///
   /// Note `lhs` and `rhs` might have the same contents even if their IDs are
-  /// different. For example two different `FunctionDeclSyntax` nodes in the
-  /// might have the exact same contents but if they occur at a different
-  /// location in the source file, they have different IDs.
-  ///
-  /// Also note that the ID of a syntax node changes when it is anchored in a
-  /// different syntax tree. Modifying any node in the syntax tree a node is
-  /// contained in generates a copy of that tree and thus changes the IDs of all
-  /// nodes in the tree, not just the modified node's children.
+  /// different. See documentation on ``SyntaxIdentifier``.
   public static func == (lhs: Syntax, rhs: Syntax) -> Bool {
     return lhs.data.nodeId == rhs.data.nodeId
   }
@@ -244,11 +237,11 @@ extension SyntaxProtocol {
     return raw.kind
   }
 
-  /// The dynamic metatype of this node. You almost always want to prefer this
-  /// over `type(of: self)` because if `self` is a `DeclSyntax` representing a
-  /// `FunctionDeclSyntax`, `type(of: self)` will return `DeclSyntax`, while
+  /// The dynamic metatype of the concrete node. You almost always want to prefer this
+  /// over `type(of: self)` because if `self` is a ``DeclSyntax`` representing a
+  /// ``FunctionDeclSyntax``, `type(of: self)` will return `DeclSyntax`, while
   /// `syntaxNodeType` looks at the dynamic kind of this node and returns
-  /// `FunctionDeclSyntax`.
+  /// ``FunctionDeclSyntax``.
   public var syntaxNodeType: SyntaxProtocol.Type {
     return self.raw.kind.syntaxNodeType
   }
@@ -780,7 +773,7 @@ public struct ReversedTokenSequence: Sequence {
     }
 
     /// Returns the next element in a ``ReversedTokenSequence``, i.e. the one
-    /// that occured before the current token in source order.
+    /// that occurred before the current token in source order.
     public mutating func next() -> TokenSyntax? {
       guard let token = self.nextToken else { return nil }
       self.nextToken = token.previousToken(viewMode: viewMode)

Sources/SwiftSyntax/SyntaxArena.swift

@@ -21,18 +21,20 @@
 /// chunk of memory at a time, which it can then use to store syntax nodes in.
 /// This way, only a single memory allocation needs to be performed for multiple
 /// syntax nodes and since memory allocations have a non-trivial cost, this
-/// signficiantly speeds up parsing.
+/// significantly speeds up parsing.
 ///
 /// 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 before any
+/// be manually ensured that the ``SyntaxArena`` is not deallocated while any
 /// of its nodes are being accessed. The ``SyntaxData`` type ensures this as
-/// follows: Each node retains its parent ``SyntaxData``, thus keeping it alive.
-/// The tree’s root keeps the ``SyntaxArena`` it is contained in alive. And if
-/// any children of this tree are allocated within a different ``SyntaxArena``,
-/// the root arena keeps those arenas alive via the `childRefs` property.
+/// follows:
+/// - The root node has a strong reference to its ``SyntaxArena``
+/// - 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/SyntaxData.swift

@@ -93,10 +93,10 @@ public struct SyntaxIndexInTree: Comparable, Hashable {
   }
 }
 
-/// Provides a stable and unique identity for `Syntax` nodes.
+/// Provides a stable and unique identity for ``Syntax`` nodes.
 ///
 /// Note that two nodes might have the same contents even if their IDs are
-/// different. For example two different `FunctionDeclSyntax` nodes in the
+/// different. For example two different ``FunctionDeclSyntax`` nodes in the
 /// might have the exact same contents but if they occur at a different
 /// location in the source file, they have different IDs.
 ///

Sources/SwiftSyntax/SyntaxText.swift

@@ -222,7 +222,7 @@ extension SyntaxText: CustomStringConvertible {
 
 extension SyntaxText: CustomDebugStringConvertible {
   /// The string value of this text, which may be lossy if the text contains
-  /// invalid Unicode.
+  /// invalid Unicode. Don’t rely on this value being stable.
   public var debugDescription: String { description.debugDescription }
 }
 

Sources/SwiftSyntax/TokenDiagnostic.swift

@@ -116,9 +116,9 @@ public struct TokenDiagnostic: Hashable {
   /// Since the offset within the token is represented by 16 bits only,
   /// diagnostics that are more than 2^16 bytes from the token's start cannot
   /// be represented. In that case, emit a `tokenDiagnosticOffsetOverflow`
-  /// diagnostic at the token’s start. 2^16 are quite a lot of characters for
+  /// diagnostic at the token’s start. 2^16 is quite a lot of characters for
   /// a single token (even when we include comments as trivia), so we don’t
-  /// expect to hit this case in the vast majority.
+  /// expect to hit this case most of the time.
   public init(_ kind: Kind, byteOffset: Int) {
     precondition(byteOffset >= 0)
     // `type(of: self.byteOffset).max` gets optimized to a constant

Sources/SwiftSyntax/TokenSyntax.swift

@@ -152,7 +152,7 @@ public struct TokenSyntax: SyntaxProtocol, SyntaxHashable {
 }
 
 extension TokenSyntax: CustomReflectable {
-  /// A custom mirror that shows the token properties in a better for, making
+  /// A custom mirror that shows the token properties in a simpler form, making
   /// the debug output of the token easier to read.
   public var customMirror: Mirror {
     return Mirror(