From b5c7d973c93764078a3099f1a468f3c924051ea9 Mon Sep 17 00:00:00 2001 From: Alex Hoppen Date: Wed, 24 May 2023 19:12:33 -0700 Subject: [PATCH] Improve doc comments based on review comments --- .../LexerDiagnosticMessages.swift | 4 +-- Sources/SwiftParserDiagnostics/Utils.swift | 10 ++++---- Sources/SwiftSyntax/BumpPtrAllocator.swift | 6 ++--- Sources/SwiftSyntax/SourceLocation.swift | 12 +++++---- Sources/SwiftSyntax/Syntax.swift | 25 +++++++------------ Sources/SwiftSyntax/SyntaxArena.swift | 16 ++++++------ Sources/SwiftSyntax/SyntaxData.swift | 4 +-- Sources/SwiftSyntax/SyntaxText.swift | 2 +- Sources/SwiftSyntax/TokenDiagnostic.swift | 4 +-- Sources/SwiftSyntax/TokenSyntax.swift | 2 +- 10 files changed, 40 insertions(+), 45 deletions(-) diff --git a/Sources/SwiftParserDiagnostics/LexerDiagnosticMessages.swift b/Sources/SwiftParserDiagnostics/LexerDiagnosticMessages.swift index e08b6be41b6..5c528d9e503 100644 --- a/Sources/SwiftParserDiagnostics/LexerDiagnosticMessages.swift +++ b/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 [ diff --git a/Sources/SwiftParserDiagnostics/Utils.swift b/Sources/SwiftParserDiagnostics/Utils.swift index 6a87a943a58..75a36ff6482 100644 --- a/Sources/SwiftParserDiagnostics/Utils.swift +++ b/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.. String { + func replacingLastOccurrence(of character: Character, with replacement: Character) -> String { guard let match = self.lastIndex(of: character) else { return self } diff --git a/Sources/SwiftSyntax/BumpPtrAllocator.swift b/Sources/SwiftSyntax/BumpPtrAllocator.swift index e5c4d5830b8..8843e97e0fd 100644 --- a/Sources/SwiftSyntax/BumpPtrAllocator.swift +++ b/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 = [] diff --git a/Sources/SwiftSyntax/SourceLocation.swift b/Sources/SwiftSyntax/SourceLocation.swift index 80b421ce7b4..84243324423 100644 --- a/Sources/SwiftSyntax/SourceLocation.swift +++ b/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))" } diff --git a/Sources/SwiftSyntax/Syntax.swift b/Sources/SwiftSyntax/Syntax.swift index 410f83308e5..6a539a2e525 100644 --- a/Sources/SwiftSyntax/Syntax.swift +++ b/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) diff --git a/Sources/SwiftSyntax/SyntaxArena.swift b/Sources/SwiftSyntax/SyntaxArena.swift index 1cf0f829bd6..b39f0403a82 100644 --- a/Sources/SwiftSyntax/SyntaxArena.swift +++ b/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 { diff --git a/Sources/SwiftSyntax/SyntaxData.swift b/Sources/SwiftSyntax/SyntaxData.swift index b8ddc7f641e..89952191d0e 100644 --- a/Sources/SwiftSyntax/SyntaxData.swift +++ b/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. /// diff --git a/Sources/SwiftSyntax/SyntaxText.swift b/Sources/SwiftSyntax/SyntaxText.swift index 271c4381039..89c758111de 100644 --- a/Sources/SwiftSyntax/SyntaxText.swift +++ b/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 } } diff --git a/Sources/SwiftSyntax/TokenDiagnostic.swift b/Sources/SwiftSyntax/TokenDiagnostic.swift index 8351b3fa855..07ca0dd200e 100644 --- a/Sources/SwiftSyntax/TokenDiagnostic.swift +++ b/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 diff --git a/Sources/SwiftSyntax/TokenSyntax.swift b/Sources/SwiftSyntax/TokenSyntax.swift index 3c7af91bacf..cf7affbeaa4 100644 --- a/Sources/SwiftSyntax/TokenSyntax.swift +++ b/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(