From b09c7d4d243f6aabaed3b23ec46be614caa7bf93 Mon Sep 17 00:00:00 2001
From: Matthew Bastien <matthew_bastien@apple.com>
Date: Wed, 23 Jul 2025 13:56:04 -0400
Subject: [PATCH] address review comments

---
 .../IndexStoreDB+Extensions.swift             | 30 ++++++++++++++-----
 .../DoccDocumentationHandler.swift            |  3 +-
 .../Swift/DoccDocumentation.swift             |  5 ++--
 3 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/Sources/DocCDocumentation/IndexStoreDB+Extensions.swift b/Sources/DocCDocumentation/IndexStoreDB+Extensions.swift
index 1314ab12..6a4eba86 100644
--- a/Sources/DocCDocumentation/IndexStoreDB+Extensions.swift
+++ b/Sources/DocCDocumentation/IndexStoreDB+Extensions.swift
@@ -25,13 +25,12 @@ extension CheckedIndex {
   /// the same result every time.
   package func primaryDefinitionOrDeclarationOccurrence(
     ofDocCSymbolLink symbolLink: DocCSymbolLink,
-    fetchSymbolGraph: @Sendable (_: SymbolLocation) async throws -> String?
+    fetchSymbolGraph: @Sendable (SymbolLocation) async throws -> String?
   ) async throws -> SymbolOccurrence? {
-    guard !symbolLink.components.isEmpty else {
-      return nil
+    guard let topLevelSymbolName = symbolLink.components.last?.name else {
+      throw DocCCheckedIndexError.emptyDocCSymbolLink
     }
     // Find all occurrences of the symbol by name alone
-    let topLevelSymbolName = symbolLink.components.last!.name
     var topLevelSymbolOccurrences: [SymbolOccurrence] = []
     forEachCanonicalSymbolOccurrence(byName: topLevelSymbolName) { symbolOccurrence in
       topLevelSymbolOccurrences.append(symbolOccurrence)
@@ -60,7 +59,7 @@ extension CheckedIndex {
   ///   - fetchSymbolGraph: Callback that returns a SymbolGraph for a given SymbolLocation
   package func doccSymbolInformation(
     ofUSR usr: String,
-    fetchSymbolGraph: (_: SymbolLocation) async throws -> String?
+    fetchSymbolGraph: (SymbolLocation) async throws -> String?
   ) async throws -> DocCSymbolInformation? {
     guard let topLevelSymbolOccurrence = primaryDefinitionOrDeclarationOccurrence(ofUSR: usr) else {
       return nil
@@ -77,11 +76,11 @@ extension CheckedIndex {
     var components = [DocCSymbolInformation.Component(fromModuleName: moduleName)]
     for symbolOccurence in symbols {
       guard let rawSymbolGraph = try await fetchSymbolGraph(symbolOccurence.location) else {
-        return nil
+        throw DocCCheckedIndexError.noSymbolGraph(symbolOccurence.symbol.usr)
       }
       let symbolGraph = try JSONDecoder().decode(SymbolGraph.self, from: Data(rawSymbolGraph.utf8))
       guard let symbol = symbolGraph.symbols[symbolOccurence.symbol.usr] else {
-        return nil
+        throw DocCCheckedIndexError.symbolNotFound(symbolOccurence.symbol.usr)
       }
       components.append(DocCSymbolInformation.Component(fromSymbol: symbol))
     }
@@ -89,6 +88,23 @@ extension CheckedIndex {
   }
 }
 
+enum DocCCheckedIndexError: LocalizedError {
+  case emptyDocCSymbolLink
+  case noSymbolGraph(String)
+  case symbolNotFound(String)
+
+  var errorDescription: String? {
+    switch self {
+    case .emptyDocCSymbolLink:
+      "The provided DocCSymbolLink was empty and could not be resolved"
+    case .noSymbolGraph(let usr):
+      "Unable to locate symbol graph for \(usr)"
+    case .symbolNotFound(let usr):
+      "Symbol \(usr) was not found in its symbol graph"
+    }
+  }
+}
+
 extension SymbolOccurrence {
   func parent(_ index: CheckedIndex) -> SymbolOccurrence? {
     let allParentRelations =
diff --git a/Sources/SourceKitLSP/Documentation/DoccDocumentationHandler.swift b/Sources/SourceKitLSP/Documentation/DoccDocumentationHandler.swift
index e7716686..5d5f1572 100644
--- a/Sources/SourceKitLSP/Documentation/DoccDocumentationHandler.swift
+++ b/Sources/SourceKitLSP/Documentation/DoccDocumentationHandler.swift
@@ -71,8 +71,7 @@ extension DocumentationLanguageService {
               return try await languageService.withSnapshotFromDiskOpenedInSourcekitd(
                 uri: location.documentUri,
                 fallbackSettingsAfterTimeout: false
-              ) {
-                (snapshot, compileCommand) in
+              ) { (snapshot, compileCommand) in
                 let (_, _, symbolGraph) = try await languageService.cursorInfo(
                   snapshot,
                   compileCommand: compileCommand,
diff --git a/Sources/SourceKitLSP/Swift/DoccDocumentation.swift b/Sources/SourceKitLSP/Swift/DoccDocumentation.swift
index 289e9e60..8424c25c 100644
--- a/Sources/SourceKitLSP/Swift/DoccDocumentation.swift
+++ b/Sources/SourceKitLSP/Swift/DoccDocumentation.swift
@@ -79,8 +79,7 @@ extension SwiftLanguageService {
           try await withSnapshotFromDiskOpenedInSourcekitd(
             uri: symbolLocation.documentUri,
             fallbackSettingsAfterTimeout: false
-          ) {
-            (snapshot, compileCommand) in
+          ) { (snapshot, compileCommand) in
             let (_, _, symbolGraph) = try await self.cursorInfo(
               snapshot,
               compileCommand: compileCommand,
@@ -107,7 +106,7 @@ extension SwiftLanguageService {
     documentationManager: DocCDocumentationManager,
     catalogURL: URL?,
     for symbolUSR: String,
-    fetchSymbolGraph: @Sendable (_: SymbolLocation) async throws -> String?
+    fetchSymbolGraph: @Sendable (SymbolLocation) async throws -> String?
   ) async throws -> String? {
     guard let catalogURL else {
       return nil