Repository: apple/swift-docc (swift)

Issue:
[SR-15540] Documentation coverage "USR" column is named incorrectly

   |                  |                 |
   |------------------|-----------------|
   |Previous ID       | SR-15540      |
   |Radar             | None         |
   |Original Reporter | @franklinsch      |
   |Type              | Bug    |

   <details>
  <summary>Additional Detail from JIRA</summary>

   |                  |                 |
   |------------------|-----------------|
   |Votes             | 0         |
   |Component/s       | Swift-DocC    |
   |Labels            | Bug        |
   |Assignee          | None      |
   |Priority          | Medium      |

   

   md5: 03bfd579fe69e2e3c621d898704baf08

  </details>





**Issue Description:**


When compiling documentation with the experimental documentation support enabled, the coverage data that's emitted includes a column called "USR". The naming is incorrect because the values that DocC emits is actually the documentation links of the generated pages, rather than their USR (the USR is a compiler-generated unique string that identifies a symbol). The column should be named to something like "Documentation Link" instead.

Pull request:
<!--
If you're opening a PR to cherry-pick a change for a release branch, use this template instead:
https://github.com/apple/swift-docc/blob/main/.github/PULL_REQUEST_TEMPLATE/CHERRY_PICK.md
-->

Bug/issue #, if applicable: #205 

## Summary

Updates the "USR" title from the detailed documentation coverage to "Reference Path".

## Dependencies

None.

## Testing

1. Run the `docc preview` command adding the `--experimental-documentation coverage` and `--coverage-summary-level detailed` flags. 
2. Once the detailed documentation coverage overview appears on your console, check the column titles for "Reference Path". 

## Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

- ~[] Added tests~
- [x] Ran the `./bin/test` script and it succeeded
- ~[] Updated documentation if necessary~

Patch:
diff --git a/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift b/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift
index d17988a5d3..fac8945f7b 100644
--- a/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift
+++ b/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift
@@ -15,7 +15,7 @@ import SymbolKit
 public struct CoverageDataEntry: CustomStringConvertible, Codable {
     internal init(
         title: String,
-        usr: String,
+        referencePath: String,
         sourceLanguage: SourceLanguage,
         availableSourceLanguages: Set<SourceLanguage>,
         kind: DocumentationNode.Kind,
@@ -26,7 +26,7 @@ public struct CoverageDataEntry: CustomStringConvertible, Codable {
         kindSpecificData: KindSpecificData?
     ) {
         self.title = title
-        self.usr = usr
+        self.referencePath = referencePath
         self.sourceLanguage = sourceLanguage
         self.kind = kind
         self.hasAbstract = hasAbstract
@@ -38,7 +38,7 @@ public struct CoverageDataEntry: CustomStringConvertible, Codable {
     }
 
     internal var title: String
-    internal var usr: String
+    internal var referencePath: String
 
     internal var hasAbstract: Bool
     internal var isCurated: Bool
@@ -74,7 +74,7 @@ public struct CoverageDataEntry: CustomStringConvertible, Codable {
             ("Code Listing?", 15, \.hasCodeListing.description),
             ("Parameters", 12, it),
             ("Language", 15, \.sourceLanguage.name),
-            ("USR", 0, \.usr),
+            ("Reference Path", 0, \.referencePath),
         ]
 
     }()
@@ -194,7 +194,7 @@ extension CoverageDataEntry {
         let hasAbstract = semanticSymbol?.abstractSection != nil  // How should we this handle 'possible' failure?
         let isCurated =
             context.manuallyCuratedReferences?.contains(documentationNode.reference) ?? false
-        let usr = renderNode.identifier.description
+        let referencePath = renderNode.identifier.description
         let sourceLanguage = documentationNode.sourceLanguage
         let availableSourceLanguages = documentationNode.availableSourceLanguages
         let availability = semanticSymbol?.availability
@@ -202,7 +202,7 @@ extension CoverageDataEntry {
 
         self = try CoverageDataEntry(
             title: title.description,
-            usr: usr,
+            referencePath: referencePath,
             sourceLanguage: sourceLanguage,
             availableSourceLanguages: availableSourceLanguages,
             kind: kind,


Test patch:
diff --git a/Tests/SwiftDocCTests/Coverage/CoverageDetailedOutputTests.swift b/Tests/SwiftDocCTests/Coverage/CoverageDetailedOutputTests.swift
index 5d616764f7..dd5441ae4f 100644
--- a/Tests/SwiftDocCTests/Coverage/CoverageDetailedOutputTests.swift
+++ b/Tests/SwiftDocCTests/Coverage/CoverageDetailedOutputTests.swift
@@ -27,7 +27,7 @@ Members         | (0/0)           | (0/0)           | (0/0)
 Globals         | (0/0)           | (0/0)           | (0/0)
 
 
-Symbol Name                      Kind                             Abstract?      Curated?       Code Listing?     Parameters     Language          USR
+Symbol Name                      Kind                             Abstract?      Curated?       Code Listing?     Parameters     Language          Reference Path
 --No Symbols to display--
 
 """
@@ -38,7 +38,7 @@ Symbol Name                      Kind                             Abstract?
         let source: [CoverageDataEntry] = [
             CoverageDataEntry(
                 title: "MyDocumentedUncuratedClass",
-                usr: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
+                referencePath: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
                 sourceLanguage: .swift,
                 availableSourceLanguages: [.swift],
                 kind: .class,
@@ -61,7 +61,7 @@ Members         | (0/0)           | (0/0)           | (0/0)
 Globals         | (0/0)           | (0/0)           | (0/0)
 
 
-Symbol Name                      Kind                             Abstract?      Curated?       Code Listing?     Parameters     Language          USR
+Symbol Name                      Kind                             Abstract?      Curated?       Code Listing?     Parameters     Language          Reference Path
 MyDocumentedUncuratedClass     | Class                          | true         | false        | false           | -            | Swift           | doc://org.swift.docc.example/documentation/MyLibrary/MyClass
 
 """
@@ -72,7 +72,7 @@ MyDocumentedUncuratedClass     | Class                          | true         |
         let source: [CoverageDataEntry] = [
             CoverageDataEntry(
                 title: "MyDocumentedUncuratedClass",
-                usr: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
+                referencePath: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
                 sourceLanguage: .swift,
                 availableSourceLanguages: [.swift],
                 kind: .class,
@@ -83,7 +83,7 @@ MyDocumentedUncuratedClass     | Class                          | true         |
                 kindSpecificData: .class(memberStats: [:])),
             CoverageDataEntry(
                 title: "MyDocumentedUncuratedClassProperty",
-                usr: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass/myProperty",
+                referencePath: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass/myProperty",
                 sourceLanguage: .swift,
                 availableSourceLanguages: [.swift],
                 kind: .instanceProperty,
@@ -100,7 +100,7 @@ MyDocumentedUncuratedClass     | Class                          | true         |
             shouldGenerateDetailed: true
         )
         let expected = """
-Symbol Name                      Kind                             Abstract?      Curated?       Code Listing?     Parameters     Language          USR
+Symbol Name                      Kind                             Abstract?      Curated?       Code Listing?     Parameters     Language          Reference Path
 MyDocumentedUncuratedClass     | Class                          | true         | false        | true            | -            | Swift           | doc://org.swift.docc.example/documentation/MyLibrary/MyClass
 MyDocumentedUncuratedClassProp | Instance Property              | false        | true         | false           | -            | Swift           | doc://org.swift.docc.example/documentation/MyLibrary/MyClass/myProperty
 
diff --git a/Tests/SwiftDocCTests/Coverage/CoverageSummaryTests.swift b/Tests/SwiftDocCTests/Coverage/CoverageSummaryTests.swift
index b04095eb55..133bb41e59 100644
--- a/Tests/SwiftDocCTests/Coverage/CoverageSummaryTests.swift
+++ b/Tests/SwiftDocCTests/Coverage/CoverageSummaryTests.swift
@@ -45,7 +45,7 @@ Globals         | (0/0)           | (0/0)           | (0/0)
         let source: [CoverageDataEntry] = [
             CoverageDataEntry(
                 title: "MyDocumentedUncuratedClass",
-                usr: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
+                referencePath: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
                 sourceLanguage: .swift,
                 availableSourceLanguages: [.swift],
                 kind: .class,
@@ -75,7 +75,7 @@ Globals         | (0/0)           | (0/0)           | (0/0)
         let source: [CoverageDataEntry] = [
             CoverageDataEntry(
                 title: "MyDocumentedUncuratedClass",
-                usr: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
+                referencePath: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass",
                 sourceLanguage: .swift,
                 availableSourceLanguages: [.swift],
                 kind: .class,
@@ -86,7 +86,7 @@ Globals         | (0/0)           | (0/0)           | (0/0)
                 kindSpecificData: .class(memberStats: [:])),
             CoverageDataEntry(
                 title: "MyDocumentedUncuratedClassProperty",
-                usr: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass/myProperty",
+                referencePath: "doc://org.swift.docc.example/documentation/MyLibrary/MyClass/myProperty",
                 sourceLanguage: .swift,
                 availableSourceLanguages: [.swift],
                 kind: .instanceProperty,