Merge pull request swiftlang#1670 from ahoppen/ahoppen/write-documentation

Add documentation to (nearly) all public functions in the SwiftSyntax module

Author: ahoppen

Sources/SwiftParserDiagnostics/MultiLineStringLiteralDiagnosticsGenerator.swift

@@ -61,7 +61,7 @@ final class MultiLineStringLiteralIndentatinDiagnosticsGenerator: SyntaxVisitor
     let indentationStartIndex = tokenLeadingTrivia.pieces.lastIndex(where: { $0.isNewline })?.advanced(by: 1) ?? tokenLeadingTrivia.startIndex
     let preIndentationTrivia = Trivia(pieces: tokenLeadingTrivia[0..<indentationStartIndex])
     let indentationTrivia = Trivia(pieces: tokenLeadingTrivia[indentationStartIndex...])
-    var positionOffset = preIndentationTrivia.byteSize
+    var positionOffset = preIndentationTrivia.sourceLength.utf8Length
 
     for (invalidTriviaPiece, missingTriviaPiece) in zip(indentationTrivia.decomposed, closeQuote.leadingTrivia.decomposed) {
       if invalidTriviaPiece == missingTriviaPiece {

Sources/SwiftParserDiagnostics/Utils.swift

@@ -11,6 +11,9 @@
 //===----------------------------------------------------------------------===//
 
 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.
   func withFirstLetterUppercased() -> String {
     if let firstLetter = self.first {
       return firstLetter.uppercased() + self.dropFirst()
@@ -19,13 +22,19 @@ extension String {
     }
   }
 
+  /// Replace the first occurance 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 {
     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`.
+  ///
+  /// If `character` does not occur in this string, no change is made.
   func replacingLastOccurence(of character: Character, with replacement: Character) -> String {
     guard let match = self.lastIndex(of: character) else {
       return self

Sources/SwiftSyntax/BumpPtrAllocator.swift

@@ -10,7 +10,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Bump-pointer allocation.
+/// 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)
 public class BumpPtrAllocator {
   typealias Slab = UnsafeMutableRawBufferPointer
@@ -35,6 +37,9 @@ 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.
   public init(slabSize: Int) {
     self.slabSize = slabSize
     slabs = []

Sources/SwiftSyntax/IncrementalParseTransition.swift

@@ -206,6 +206,8 @@ public struct IncrementalParseLookup {
   fileprivate let transition: IncrementalParseTransition
   fileprivate var cursor: SyntaxCursor
 
+  /// Create a new `IncrementalParseLookup` that can look nodes up based on the
+  /// given ``IncrementalParseTransition``.
   public init(transition: IncrementalParseTransition) {
     self.transition = transition
     self.cursor = .init(root: transition.previousTree.data)

Sources/SwiftSyntax/Raw/RawSyntax.swift

@@ -342,10 +342,12 @@ extension RawSyntax {
 }
 
 extension RawSyntax {
+  @_spi(RawSyntax)
   public func toOpaque() -> UnsafeRawPointer {
     UnsafeRawPointer(pointer)
   }
 
+  @_spi(RawSyntax)
   public static func fromOpaque(_ pointer: UnsafeRawPointer) -> RawSyntax {
     Self(pointer: pointer.assumingMemoryBound(to: RawSyntaxData.self))
   }
@@ -866,6 +868,7 @@ extension RawSyntax: CustomDebugStringConvertible {
     target.write(")")
   }
 
+  @_spi(RawSyntax)
   public var debugDescription: String {
     var string = ""
     debugWrite(to: &string, indent: 0, withChildren: false)
@@ -874,6 +877,7 @@ extension RawSyntax: CustomDebugStringConvertible {
 }
 
 extension RawSyntax: CustomReflectable {
+  @_spi(RawSyntax)
   public var customMirror: Mirror {
 
     let mirrorChildren: [Any]

Sources/SwiftSyntax/Raw/RawSyntaxNodeProtocol.swift

@@ -58,15 +58,19 @@ public extension RawSyntaxNodeProtocol {
 
 /// `RawSyntax` itself conforms to `RawSyntaxNodeProtocol`.
 extension RawSyntax: RawSyntaxNodeProtocol {
+  @_spi(RawSyntax)
   public static func isKindOf(_ raw: RawSyntax) -> Bool {
     return true
   }
+
+  @_spi(RawSyntax)
   public var raw: RawSyntax { self }
 
   init(raw: RawSyntax) {
     self = raw
   }
 
+  @_spi(RawSyntax)
   public init(_ other: some RawSyntaxNodeProtocol) {
     self.init(raw: other.raw)
   }
@@ -75,6 +79,7 @@ extension RawSyntax: RawSyntaxNodeProtocol {
 #if swift(<5.8)
 // Cherry-pick this function from SE-0370
 extension Slice {
+  @_spi(RawSyntax)
   @inlinable
   public func initialize<S>(
     from source: S
@@ -90,17 +95,20 @@ extension Slice {
 
 @_spi(RawSyntax)
 public struct RawTokenSyntax: RawSyntaxNodeProtocol {
+  @_spi(RawSyntax)
   public typealias SyntaxType = TokenSyntax
 
   @_spi(RawSyntax)
   public var tokenView: RawSyntaxTokenView {
     return raw.tokenView!
   }
 
+  @_spi(RawSyntax)
   public static func isKindOf(_ raw: RawSyntax) -> Bool {
     return raw.kind == .token
   }
 
+  @_spi(RawSyntax)
   public var raw: RawSyntax
 
   init(raw: RawSyntax) {
@@ -112,43 +120,53 @@ public struct RawTokenSyntax: RawSyntaxNodeProtocol {
     self.raw = raw
   }
 
+  @_spi(RawSyntax)
   public init?(_ other: some RawSyntaxNodeProtocol) {
     guard Self.isKindOf(other.raw) else { return nil }
     self.init(unchecked: other.raw)
   }
 
+  @_spi(RawSyntax)
   public var tokenKind: RawTokenKind {
     return tokenView.rawKind
   }
 
+  @_spi(RawSyntax)
   public var tokenText: SyntaxText {
     return tokenView.rawText
   }
 
+  @_spi(RawSyntax)
   public var byteLength: Int {
     return raw.byteLength
   }
 
+  @_spi(RawSyntax)
   public var presence: SourcePresence {
     tokenView.presence
   }
 
+  @_spi(RawSyntax)
   public var isMissing: Bool {
     presence == .missing
   }
 
+  @_spi(RawSyntax)
   public var leadingTriviaByteLength: Int {
     return tokenView.leadingTriviaByteLength
   }
 
+  @_spi(RawSyntax)
   public var leadingTriviaPieces: [RawTriviaPiece] {
     tokenView.leadingRawTriviaPieces
   }
 
+  @_spi(RawSyntax)
   public var trailingTriviaByteLength: Int {
     return tokenView.trailingTriviaByteLength
   }
 
+  @_spi(RawSyntax)
   public var trailingTriviaPieces: [RawTriviaPiece] {
     tokenView.trailingRawTriviaPieces
   }

Sources/SwiftSyntax/SourceLength.swift

@@ -13,13 +13,15 @@
 /// The length a syntax node spans in the source code. From any AbsolutePosition
 /// you reach a node's end location by adding its UTF-8 length.
 public struct SourceLength: Comparable {
+  /// The length in bytes when the text is represented as UTF-8.
   public let utf8Length: Int
 
   /// Construct the source length of a given text
   public init(of text: String) {
     self.utf8Length = text.utf8.count
   }
 
+  /// Construct a source length that takes up `utf8Length` bytes when represented as UTF-8.
   public init(utf8Length: Int) {
     self.utf8Length = utf8Length
   }
@@ -28,6 +30,7 @@ public struct SourceLength: Comparable {
   public static let zero: SourceLength =
     SourceLength(utf8Length: 0)
 
+  /// Returns `true` if `lhs` is shorter than `rhs`.
   public static func < (lhs: SourceLength, rhs: SourceLength) -> Bool {
     return lhs.utf8Length < rhs.utf8Length
   }
@@ -38,15 +41,18 @@ public struct SourceLength: Comparable {
     return SourceLength(utf8Length: utf8Length)
   }
 
+  /// Extend `lhs` by `rhs` bytes.
   public static func += (lhs: inout SourceLength, rhs: SourceLength) {
     lhs = lhs + rhs
   }
 
+  /// Return a source length that's `rhs` bytes shorter than `lhs`.
   public static func - (lhs: SourceLength, rhs: SourceLength) -> SourceLength {
     let utf8Length = lhs.utf8Length - rhs.utf8Length
     return SourceLength(utf8Length: utf8Length)
   }
 
+  /// Change `lhs` to be `rhs` bytes shorter than `lhs`.
   public static func -= (lhs: inout SourceLength, rhs: SourceLength) {
     lhs = lhs - rhs
   }
@@ -62,10 +68,12 @@ extension AbsolutePosition {
     return AbsolutePosition(utf8Offset: utf8Offset)
   }
 
+  /// Advance `lhs` by `rhs`, i.e. changing it to the position `rhs` bytes after `lhs`.
   public static func += (lhs: inout AbsolutePosition, rhs: SourceLength) {
     lhs = lhs + rhs
   }
 
+  /// Return the position `rhs` bytes before `lhs`.
   public static func - (
     lhs: AbsolutePosition,
     rhs: SourceLength
@@ -74,6 +82,7 @@ extension AbsolutePosition {
     return AbsolutePosition(utf8Offset: utf8Offset)
   }
 
+  /// Reverse `lhs` by `rhs`, i.e. changing it `lhs` to the position `rhs` bytes before `lhs`.
   public static func -= (lhs: inout AbsolutePosition, rhs: SourceLength) {
     lhs = lhs - rhs
   }

Sources/SwiftSyntax/SourceLocation.swift

@@ -26,11 +26,27 @@ public struct SourceLocation: Hashable, Codable, CustomDebugStringConvertible {
   /// The file in which this location resides.
   public let file: String
 
+  /// Returns the location as `<line>:<column>` for debugging purposes.
+  /// Do not rely on this output being stable.
   public var debugDescription: String {
     // Print file name?
     return "\(line):\(column)"
   }
 
+  /// Create a new source location at the specified `line` and `column` in `file`.
+  ///
+  /// - Parameters:
+  ///   - line: 1-based, i.e. the first line in the file has line number 1
+  ///   - column: The UTF-8 byte offset of the location with its line, i.e. the
+  ///             number of bytes all characters in the line before the location
+  ///             occupy when encoded as UTF-8. 1-based, i.e. the leftmost
+  ///             column in the file has column 1.
+  ///   - offset: The UTF-8 offset of the location within the entire file, i.e.
+  ///             the number of bytes all source code before the location
+  ///             occupies when encoded as UTF-8. 0-based, i.e. the first
+  ///             location in the source file has `offset` 0.
+  ///   - file: A string describing the name of the file in which this location
+  ///           is contained.
   public init(line: Int, column: Int, offset: Int, file: String) {
     self.line = line
     self.offset = offset
@@ -43,15 +59,22 @@ public struct SourceLocation: Hashable, Codable, CustomDebugStringConvertible {
 public struct SourceRange: Hashable, Codable, CustomDebugStringConvertible {
 
   /// The beginning location in the source range.
+  ///
+  /// This location is included in the range
   public let start: SourceLocation
 
   /// The beginning location in the source range.
+  ///
+  /// This location is no longer part of the range
   public let end: SourceLocation
 
+  /// A description describing this range for debugging purposes, don't rely on it.
   public var debugDescription: String {
     return "(\(start.debugDescription),\(end.debugDescription))"
   }
 
+  /// Construct a new source range, starting at `start` (inclusive) and ending
+  /// at `end` (exclusive).
   public init(start: SourceLocation, end: SourceLocation) {
     self.start = start
     self.end = end