Docs, Docs, Docs

Author: thecoolwinter

Sources/CodeEditSourceEditor/Enums/CaptureModifiers.swift

@@ -37,7 +37,8 @@ extension CaptureModifiers: CustomDebugStringConvertible {
     }
 }
 
-public struct CaptureModifierSet: OptionSet, Equatable, Hashable {
+/// A set of capture modifiers, efficiently represented by a single integer.
+public struct CaptureModifierSet: OptionSet, Equatable, Hashable, Sendable {
     public let rawValue: UInt
 
     public init(rawValue: UInt) {
@@ -54,7 +55,8 @@ public struct CaptureModifierSet: OptionSet, Equatable, Hashable {
     static let modification = CaptureModifierSet(rawValue: 1 << CaptureModifiers.modification.rawValue)
     static let documentation = CaptureModifierSet(rawValue: 1 << CaptureModifiers.documentation.rawValue)
     static let defaultLibrary = CaptureModifierSet(rawValue: 1 << CaptureModifiers.defaultLibrary.rawValue)
-
+    
+    /// All values in the set.
     var values: [CaptureModifiers] {
         var rawValue = self.rawValue
         var values: [Int8] = []

Sources/CodeEditSourceEditor/Highlighting/HighlighProviding/HighlightProviderState.swift

@@ -16,6 +16,15 @@ protocol HighlightProviderStateDelegate: AnyObject {
     func applyHighlightResult(provider: ProviderID, highlights: [HighlightRange], rangeToHighlight: NSRange)
 }
 
+/// Keeps track of the valid and pending indices for a single highlight provider in the editor.
+///
+/// When ranges are invalidated, edits are made, or new text is made visible, this class is notified and queries its
+/// highlight provider for invalidated indices.
+///
+/// Once it knows which indices were invalidated by the edit, it queries the provider for highlights and passes the
+/// results to a ``StyledRangeContainer`` to eventually be applied to the editor.
+///
+/// This class will also chunk the invalid ranges to avoid performing a massive highlight query.
 @MainActor
 class HighlightProviderState {
     private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "", category: "HighlightProviderState")

Sources/CodeEditSourceEditor/Highlighting/Highlighter.swift

@@ -12,50 +12,53 @@ import SwiftTreeSitter
 import CodeEditLanguages
 import OSLog
 
-/*
- +---------------------------------+
- |          Highlighter            |
- |                                 |
- |  - highlightProviders[]         |
- |  - styledRangeContainer         |
- |                                 |
- |  + refreshHighlightsIn(range:)  |
- +---------------------------------+
- |
- |
- v
- +-------------------------------+             +-----------------------------+
- |    RangeCaptureContainer      |   ------>   |         RangeStore          |
- |                               |             |                             |
- |  - manages combined ranges    |             |  - stores raw ranges &      |
- |  - layers highlight styles    |             |    captures                 |
- |  + getAttributesForRange()    |             +-----------------------------+
- +-------------------------------+
- ^
- |
- |
- +-------------------------------+
- |   HighlightProviderState[]    |   (one for each provider)
- |                               |
- |  - keeps valid/invalid ranges |
- |  - queries providers (async)  |
- |  + updateStyledRanges()       |
- +-------------------------------+
- ^
- |
- |
- +-------------------------------+
- |   HighlightProviding Object   |  (tree-sitter, LSP, spellcheck)
- +-------------------------------+
- */
-
-/// The `Highlighter` class handles efficiently highlighting the `TextView` it's provided with.
-/// It will listen for text and visibility changes, and highlight syntax as needed.
+/// This class manages fetching syntax highlights from providers, and applying those styles to the editor.
+/// Multiple highlight providers can be used to style the editor.
+///
+/// This class manages multiple objects that help perform this task:
+/// - ``StyledRangeContainer``
+/// - ``StyledRangeStore``
+/// - ``VisibleRangeProvider``
+/// - ``HighlightProviderState``
+///
+/// A hierarchal overview of the highlighter system.
+/// ```
+/// +---------------------------------+
+/// |          Highlighter            |
+/// |                                 |
+/// |  - highlightProviders[]         |
+/// |  - styledRangeContainer         |
+/// |                                 |
+/// |  + refreshHighlightsIn(range:)  |
+/// +---------------------------------+
+/// |
+/// | Queries coalesced styles
+/// v
+/// +-------------------------------+             +-----------------------------+
+/// |    StyledRangeContainer       |   ------>   |      StyledRangeStore[]     |
+/// |                               |             |                             | Stores styles for one provider
+/// |  - manages combined ranges    |             |  - stores raw ranges &      |
+/// |  - layers highlight styles    |             |    captures                 |
+/// |  + getAttributesForRange()    |             +-----------------------------+
+/// +-------------------------------+
+/// ^
+/// | Sends highlighted runs
+/// |
+/// +-------------------------------+
+/// |   HighlightProviderState[]    |   (one for each provider)
+/// |                               |
+/// |  - keeps valid/invalid ranges |
+/// |  - queries providers (async)  |
+/// |  + updateStyledRanges()       |
+/// +-------------------------------+
+/// ^
+/// | Performs edits and sends highlight deltas, as well as calculates syntax captures for ranges
+/// |
+/// +-------------------------------+
+/// |   HighlightProviding Object   |  (tree-sitter, LSP, spellcheck)
+/// +-------------------------------+
+/// ```
 ///
-/// One should rarely have to directly modify or call methods on this class. Just keep it alive in
-/// memory and it will listen for bounds changes, text changes, etc. However, to completely invalidate all
-/// highlights use the ``invalidate()`` method to re-highlight all (visible) text, and the ``setLanguage``
-/// method to update the highlighter with a new language if needed.
 @MainActor
 class Highlighter: NSObject {
     static private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "", category: "Highlighter")

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeContainer.swift

@@ -12,17 +12,34 @@ protocol StyledRangeContainerDelegate: AnyObject {
     func styleContainerDidUpdate(in range: NSRange)
 }
 
+/// Stores styles for any number of style providers. Provides an API for providers to store their highlights, and for
+/// the overlapping highlights to be queried for a final highlight pass.
+///
+/// See ``runsIn(range:)`` for more details on how conflicting highlights are handled.
 @MainActor
 class StyledRangeContainer {
     var _storage: [ProviderID: StyledRangeStore] = [:]
     weak var delegate: StyledRangeContainerDelegate?
-
+    
+    /// Initialize the container with a list of provider identifiers. Each provider is given an id, they should be
+    /// passed on here so highlights can be associated with a provider for conflict resolution.
+    /// - Parameters:
+    ///   - documentLength: The length of the document.
+    ///   - providers: An array of identifiers given to providers.
     init(documentLength: Int, providers: [ProviderID]) {
         for provider in providers {
             _storage[provider] = StyledRangeStore(documentLength: documentLength)
         }
     }
 
+    /// Coalesces all styled runs into a single continuous array of styled runs.
+    ///
+    /// When there is an overlapping, conflicting style (eg: provider 1 gives `.comment` to the range `0..<2`, and
+    /// provider 2 gives `.string` to `1..<2`), the provider with a lower identifier will be prioritized. In the example
+    /// case, the final value would be `0..<1=.comment` and `1..<2=.string`.
+    ///
+    /// - Parameter range: The range to query.
+    /// - Returns: An array of continuous styled runs.
     func runsIn(range: NSRange) -> [HighlightedRun] {
         // Ordered by priority, lower = higher priority.
         var allRuns = _storage.sorted(by: { $0.key < $1.key }).map { $0.value.runs(in: range.intRange) }
@@ -68,6 +85,12 @@ class StyledRangeContainer {
 }
 
 extension StyledRangeContainer: HighlightProviderStateDelegate {
+    /// Applies a highlight result from a highlight provider to the storage container.
+    /// - Parameters:
+    ///   - provider: The provider sending the highlights.
+    ///   - highlights: The highlights provided. These cannot be outside the range to highlight, must be ordered by
+    ///                 position, but do not need to be continuous. Ranges not included in these highlights will be saved as empty.
+    ///   - rangeToHighlight: The range to apply the highlights to.
     func applyHighlightResult(provider: ProviderID, highlights: [HighlightRange], rangeToHighlight: NSRange) {
         assert(rangeToHighlight != .notFound, "NSNotFound is an invalid highlight range")
         guard let storage = _storage[provider] else {

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeStore/HighlightedRun.swift

@@ -19,19 +19,19 @@ struct HighlightedRun: Equatable, Hashable {
         capture == nil && modifiers.isEmpty
     }
 
-    mutating func combineLowerPriority(_ other: borrowing HighlightedRun) {
+    mutating package func combineLowerPriority(_ other: borrowing HighlightedRun) {
         if self.capture == nil {
             self.capture = other.capture
         }
         self.modifiers.formUnion(other.modifiers)
     }
 
-    mutating func combineHigherPriority(_ other: borrowing HighlightedRun) {
+    mutating package func combineHigherPriority(_ other: borrowing HighlightedRun) {
         self.capture = other.capture ?? self.capture
         self.modifiers.formUnion(other.modifiers)
     }
 
-    mutating func subtractLength(_ other: borrowing HighlightedRun) {
+    mutating package func subtractLength(_ other: borrowing HighlightedRun) {
         self.length -= other.length
     }
 }

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeStore/StyledRangeStore.swift

@@ -26,7 +26,10 @@ final class StyledRangeStore {
     }
 
     // MARK: - Core
-
+    
+    /// Find all runs in a range.
+    /// - Parameter range: The range to query.
+    /// - Returns: A continuous array of runs representing the queried range.
     func runs(in range: Range<Int>) -> [Run] {
         assert(range.lowerBound >= 0, "Negative lowerBound")
         assert(range.upperBound <= _guts.count(in: OffsetMetric()), "upperBound outside valid range")
@@ -49,13 +52,22 @@ final class StyledRangeStore {
 
         return runs
     }
-
+    
+    /// Sets a capture and modifiers for a range.
+    /// - Parameters:
+    ///   - capture: The capture to set.
+    ///   - modifiers: The modifiers to set.
+    ///   - range: The range to write to.
     func set(capture: CaptureName, modifiers: CaptureModifierSet, for range: Range<Int>) {
         assert(range.lowerBound >= 0, "Negative lowerBound")
         assert(range.upperBound <= _guts.count(in: OffsetMetric()), "upperBound outside valid range")
         set(runs: [Run(length: range.length, capture: capture, modifiers: modifiers)], for: range)
     }
-
+    
+    /// Replaces a range in the document with an array of runs.
+    /// - Parameters:
+    ///   - runs: The runs to insert.
+    ///   - range: The range to replace.
     func set(runs: [Run], for range: Range<Int>) {
         _guts.replaceSubrange(
             range,
@@ -71,6 +83,7 @@ final class StyledRangeStore {
 // MARK: - Storage Sync
 
 extension StyledRangeStore {
+    /// Handles keeping the internal storage in sync with the document.
     func storageUpdated(replacedCharactersIn range: Range<Int>, withCount newLength: Int) {
         assert(range.lowerBound >= 0, "Negative lowerBound")
         assert(range.upperBound <= _guts.count(in: OffsetMetric()), "upperBound outside valid range")

Sources/CodeEditSourceEditor/Highlighting/VisibleRangeProvider.swift

@@ -13,6 +13,8 @@ protocol VisibleRangeProviderDelegate: AnyObject {
     func visibleSetDidUpdate(_ newIndices: IndexSet)
 }
 
+/// Provides information to ``HighlightProviderState``s about what text is visible in the editor. Keeps it's contents
+/// in sync with a text view and notifies listeners about changes so highlights can be applied to newly visible indices.
 @MainActor
 class VisibleRangeProvider {
     private weak var textView: TextView?