Correct source code locations of link diagnostics for Objective-C doc comments (#734)

* rdar://102855081

Correct the line and character locations of invalid link diagnostics in
Objective-C source code doc comments.

Previously, DocumentationContext#resolveLinks would use the default
symbol to calculate the offset of each doc comment in the source file.
However, the default symbol is always set to a Swift symbol even for
Objective-C source code doc comments. This lead to a bug when
Objective-C diagnostics would always use a zero offset.

Instead, save the offset of each doc comment in the DocumentationChunk
structure, which is initialized using the documented symbol, i.e. the
Swift or Objective-C symbol which actually contains the doc comment.

Also decrement the line and character indexes by 1 for both Objective-C
doc comments so Xcode displays them in the proper location.

Author: patshaughnessy

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -574,7 +574,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
                     case _ where documentationNode.semantic is Article,
                             .documentationExtension:
                         source = documentLocationMap[reference]
-                    case .sourceCode(location: let location):
+                    case .sourceCode(let location, _):
                         // For symbols, first check if we should reference resolve
                         // inherited docs or not. If we don't inherit the docs
                         // we should also skip reference resolving the chunk.
@@ -622,11 +622,10 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
                     var problems = resolver.problems
 
-                    if case DocumentationNode.DocumentationChunk.Source.sourceCode = doc.source,
-                       let docs = documentationNode.symbol?.docComment {
+                    if case .sourceCode(_, let offset) = doc.source {
                         // Offset all problem ranges by the start location of the
                         // source comment in the context of the complete file.
-                        if let docRange = docs.lines.first?.range {
+                        if let docRange = offset {
                             for i in problems.indices {
                                 problems[i].offsetWithRange(docRange)
                             }

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -79,7 +79,7 @@ public struct DocumentationNode {
             /// The documentation comes from a documentation extension file.
             case documentationExtension
             /// The documentation comes from an in-source documentation comment.
-            case sourceCode(location: SymbolGraph.Symbol.Location?)
+            case sourceCode(location: SymbolGraph.Symbol.Location?, offset: SymbolGraph.LineList.SourceRange?)
         }
 
         let source: Source
@@ -145,7 +145,7 @@ public struct DocumentationNode {
         self.semantic = semantic
         self.symbol = nil
         self.platformNames = platformNames
-        self.docChunks = [DocumentationChunk(source: .sourceCode(location: nil), markup: markup)]
+        self.docChunks = [DocumentationChunk(source: .sourceCode(location: nil, offset: nil), markup: markup)]
         self.isVirtual = isVirtual
 
         if let article = semantic as? Article {
@@ -440,7 +440,8 @@ public struct DocumentationNode {
 
             let documentOptions: ParseOptions = [.parseBlockDirectives, .parseSymbolLinks, .parseMinimalDoxygen]
             let docCommentMarkup = Document(parsing: docCommentString, options: documentOptions)
-            
+            let offset = symbol.offsetAdjustedForInterfaceLanguage()
+
             let docCommentDirectives = docCommentMarkup.children.compactMap({ $0 as? BlockDirective })
             if !docCommentDirectives.isEmpty {
                 let location = symbol.mixins.getValueIfPresent(
@@ -475,7 +476,7 @@ public struct DocumentationNode {
 
                     var problem = Problem(diagnostic: diagnostic, possibleSolutions: [])
 
-                    if let offset = docComment.lines.first?.range {
+                    if let offset = offset {
                         problem.offsetWithRange(offset)
                     }
 
@@ -485,7 +486,10 @@ public struct DocumentationNode {
 
             documentationChunks = [
                 DocumentationChunk(
-                    source: .sourceCode(location: symbol.mixins.getValueIfPresent(for: SymbolGraph.Symbol.Location.self)),
+                    source: .sourceCode(
+                        location: symbol.mixins.getValueIfPresent(for: SymbolGraph.Symbol.Location.self),
+                        offset: offset
+                    ),
                     markup: docCommentMarkup
                 )
             ]
@@ -502,7 +506,7 @@ public struct DocumentationNode {
             }
         } else {
             markup = Document()
-            documentationChunks = [DocumentationChunk(source: .sourceCode(location: nil), markup: markup)]
+            documentationChunks = [DocumentationChunk(source: .sourceCode(location: nil, offset: nil), markup: markup)]
         }
 
         return (markup: markup, docChunks: documentationChunks)

Sources/SwiftDocC/Utility/SymbolExtensions.swift

@@ -0,0 +1,38 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import SymbolKit
+
+extension SymbolGraph.Symbol {
+
+    /// Return the offset of this symbol's doc comment in the original source code file,
+    /// adjusted for the interface language as follows:
+    ///
+    /// - Objective-C: subtract one from the start/end lines, and the start/end characters
+    /// - Swift and other languages: return the original offset
+    ///
+    /// - Returns: A ``SourceRange`` or nil if this symbol has no doc comment.
+    func offsetAdjustedForInterfaceLanguage() -> SymbolGraph.LineList.SourceRange? {
+        guard let range = docComment?.lines.first?.range else {
+            return nil
+        }
+        // Return the original range for Swift and other languages
+        guard SourceLanguage(knownLanguageIdentifier: identifier.interfaceLanguage) == .objectiveC else {
+            return range
+        }
+        // Decrement the line and character indexes for Objective-C
+        let start = range.start
+        let end = range.end
+        return SymbolGraph.LineList.SourceRange(
+            start: .init(line: start.line-1, character: start.character-1),
+            end: .init(line: end.line-1, character: end.character-1)
+        )
+    }
+}

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -3908,6 +3908,25 @@ let expected = """
             "Expectedly returned non-nil value for non-symbol content."
         )
     }
+
+    func testDiagnosticLocations() throws {
+        // The ObjCFrameworkWithInvalidLink.docc test bundle contains symbol
+        // graphs for both Obj-C and Swift, built after setting:
+        //   "Build Multi-Language Documentation for Objective-C Only Targets" = true.
+        // One doc comment in the Obj-C header file contains an invalid doc
+        // link on line 24, columns 56-63:
+        // "Log a hello world message. This line contains an ``invalid`` link."
+        let (_, _, context) = try testBundleAndContext(copying: "ObjCFrameworkWithInvalidLink")
+        let problems = context.problems
+        XCTAssertEqual(1, problems.count)
+        let problem = try XCTUnwrap(problems.first)
+        let basename = try XCTUnwrap(problem.diagnostic.source?.lastPathComponent)
+        XCTAssertEqual("HelloWorldFramework.h", basename)
+        let start = Markdown.SourceLocation(line: 24, column: 56, source: nil)
+        let end = Markdown.SourceLocation(line: 24, column: 63, source: nil)
+        let range = try XCTUnwrap(problem.diagnostic.range)
+        XCTAssertEqual(start..<end, range)
+    }
 }
 
 func assertEqualDumps(_ lhs: String, _ rhs: String, file: StaticString = #file, line: UInt = #line) {