Docs

Author: thecoolwinter

CodeEdit/Features/Editor/Views/CodeFileView.swift

@@ -163,6 +163,7 @@ struct CodeFileView: View {
             bracketPairHighlight = getBracketPairHighlight()
         }
         .onReceive(codeFile.$languageServerObjects) { languageServerObjects in
+            // This will not be called in single-file views (for now) but is safe to listen to either way
             updateHighlightProviders(lspHighlightProvider: languageServerObjects.highlightProvider)
         }
     }

CodeEdit/Features/LSP/Features/SemanticTokens/SemanticTokenStorage/GenericSemanticTokenStorage.swift

@@ -9,10 +9,10 @@ import Foundation
 import LanguageServerProtocol
 import CodeEditSourceEditor
 
-/// Defines a protocol for an object to provide a storage mechanism for semantic tokens.
+/// Defines a protocol for an object to provide storage for semantic tokens.
 /// 
-/// There is only one concrete type that conforms to this in CE, but this protocol is useful  in testing.
-/// See ``SemanticTokenStorage`` for use.
+/// There is only one concrete type that conforms to this in CE, but this protocol is useful in testing.
+/// See ``SemanticTokenStorage``.
 protocol GenericSemanticTokenStorage: AnyObject {
     var lastResultId: String? { get }
     var hasTokens: Bool { get }

CodeEdit/Features/LSP/Features/SemanticTokens/SemanticTokenStorage/SemanticTokenRange.swift

@@ -5,6 +5,7 @@
 //  Created by Khan Winter on 12/26/24.
 //
 
+/// Represents the range of a semantic token.
 struct SemanticTokenRange {
     let line: UInt32
     let char: UInt32

CodeEdit/Features/LSP/Features/SemanticTokens/SemanticTokenStorage/SemanticTokenStorage.swift

@@ -9,10 +9,10 @@ import Foundation
 import LanguageServerProtocol
 import CodeEditSourceEditor
 
-/// This class provides an efficient storage mechanism for semantic token data.
+/// This class provides storage for semantic token data.
 ///
-/// The LSP spec requires that clients keep the original compressed data to apply delta edits to. The delta updates may
-/// come as a delta to a single number in the compressed array. This class maintains a current state of compressed
+/// The LSP spec requires that clients keep the original compressed data to apply delta edits. Delta updates may
+/// appear as a delta to a single number in the compressed array. This class maintains the current state of compressed
 /// tokens and their decoded counterparts. It supports applying delta updates from the language server.
 ///
 /// See ``SemanticTokenHighlightProvider`` for it's connection to the editor view.
@@ -34,18 +34,23 @@ final class SemanticTokenStorage: GenericSemanticTokenStorage {
 
     var state: CurrentState?
 
+    /// Create an empty storage object.
     init() {
         state = nil
     }
 
     // MARK: - Storage Conformance
-
+    
+    /// Finds all tokens in the given range.
+    /// - Parameter range: The range to query.
+    /// - Returns: All tokens found in the range.
     func getTokensFor(range: LSPRange) -> [SemanticToken] {
         guard let state = state, !state.tokens.isEmpty else {
             return []
         }
         var tokens: [SemanticToken] = []
 
+        // Perform a binary search
         guard var idx = findLowerBound(in: range, data: state.tokens[...]) else {
             return []
         }
@@ -57,7 +62,9 @@ final class SemanticTokenStorage: GenericSemanticTokenStorage {
 
         return tokens
     }
-
+    
+    /// Clear the current state and set a new one.
+    /// - Parameter data: The semantic tokens to set as the current state.
     func setData(_ data: borrowing SemanticTokens) {
         state = CurrentState(resultId: data.resultId, tokenData: data.data, tokens: data.decode())
     }
@@ -67,10 +74,11 @@ final class SemanticTokenStorage: GenericSemanticTokenStorage {
     /// To calculate invalidated ranges:
     /// - Grabs all semantic tokens that *will* be updated and invalidates their ranges
     /// - Loops over all inserted tokens and invalidates their ranges
-    /// This may result in duplicated ranges. It's up to the caller to de-duplicate if necessary.
+    /// This may result in duplicated ranges. It's up to the caller to de-duplicate if necessary. See
+    /// ``SemanticTokenStorage/invalidatedRanges(startIdx:length:data:)``.
     ///
     /// - Parameter deltas: The deltas to apply.
-    /// - Returns: All ranges invalidated by the applied deltas.
+    /// - Returns: Ranges invalidated by the applied deltas.
     func applyDelta(_ deltas: SemanticTokensDelta) -> [SemanticTokenRange] {
         assert(state != nil, "State should be set before applying any deltas.")
         guard var tokenData = state?.tokenData else { return [] }
@@ -117,7 +125,17 @@ final class SemanticTokenStorage: GenericSemanticTokenStorage {
     }
 
     // MARK: - Invalidated Indices
-
+    
+    /// Calculate what document ranges are invalidated due to changes in the compressed token data.
+    ///
+    /// This overestimates invalidated ranges by assuming all tokens touched by a change are invalid. All this does is
+    /// find what tokens are being updated by a delta and return them.
+    ///
+    /// - Parameters:
+    ///   - startIdx: The start index of the compressed token data an edits start at.
+    ///   - length: The length of any edits.
+    ///   - data: A reference to the compressed token data.
+    /// - Returns: All token ranges included in the range of the edit.
     func invalidatedRanges(startIdx: UInt, length: UInt, data: ArraySlice<UInt32>) -> [SemanticTokenRange] {
         var ranges: [SemanticTokenRange] = []
         var idx = startIdx - (startIdx % 5)