add a heuristic that chooses the documented overload among an ambiguous overload list, if exactly one such overload exists

Author: tayloraswift

Sources/LinkResolution/UCF.CausalOverload.swift

@@ -16,16 +16,21 @@ extension UCF
         public
         let hash:FNV24
 
+        public
+        let documented:Bool
+
         @inlinable public
         init(phylum:Phylum.Decl,
             decl:Symbol.Decl,
             heir:Symbol.Decl?,
-            hash:FNV24)
+            hash:FNV24,
+            documented:Bool)
         {
             self.phylum = phylum
             self.decl = decl
             self.heir = heir
             self.hash = hash
+            self.documented = documented
         }
     }
 }

Sources/LinkResolution/UCF.PackageOverload.swift

@@ -16,6 +16,8 @@ extension UCF
         public
         let hash:FNV24
 
+        public
+        let documented:Bool
         /// Used for display purposes. This is not necessarily the symbol from which the
         /// ``hash`` was computed.
         public
@@ -26,12 +28,14 @@ extension UCF
             decl:Int32,
             heir:Int32?,
             hash:FNV24,
+            documented:Bool,
             id:Symbol.Decl)
         {
             self.phylum = phylum
             self.decl = decl
             self.heir = heir
             self.hash = hash
+            self.documented = documented
             self.id = id
         }
     }

Sources/LinkResolution/UCF.Resolution.swift

@@ -11,3 +11,31 @@ extension UCF
         case module(Symbol.Module)
     }
 }
+extension UCF.Resolution where Overload:UCF.ResolvableOverload
+{
+    static func choose(among overloads:[Symbol.Decl: Overload], 
+        rejected:[Symbol.Decl: Overload]) -> Self
+    {
+        var documentedOverload:Overload? 
+        var documentedCount:Int = 0
+
+        for candidate:Overload in overloads.values
+        {
+            if  candidate.documented
+            {
+                documentedOverload = candidate
+                documentedCount += 1
+            }
+        }
+
+        if  let documentedOverload:Overload, documentedCount == 1
+        {
+            return .overload(documentedOverload)
+        }
+        else 
+        {
+            return .ambiguous(overloads.values.sorted { $0.id < $1.id }, 
+                    rejected: rejected.values.sorted { $0.id < $1.id })
+        }
+    }
+}

Sources/LinkResolution/UCF.ResolutionTable.Search.swift

@@ -67,8 +67,7 @@ extension UCF.ResolutionTable.Search
         }
         else
         {
-            return .ambiguous(self.selected.values.sorted { $0.id < $1.id }, 
-                rejected: self.rejected.values.sorted { $0.id < $1.id })
+            return .choose(among: self.selected, rejected: self.rejected)
         }
     }
 
@@ -81,8 +80,7 @@ extension UCF.ResolutionTable.Search
         }
         else
         {
-            return .ambiguous(self.selected.values.sorted { $0.id < $1.id }, 
-                rejected: self.rejected.values.sorted { $0.id < $1.id })
+            return .choose(among: self.selected, rejected: self.rejected)
         }
     }
 }

Sources/LinkResolution/UCF.ResolvableOverload.swift

@@ -9,6 +9,8 @@ extension UCF
     {
         var phylum:Phylum.Decl { get }
         var hash:FNV24 { get }
+
+        var documented:Bool { get }
     }
 }
 extension UCF.ResolvableOverload

Sources/SymbolGraphCompiler/Extensions/SSGC.ModuleIndex.Feature.swift

@@ -11,18 +11,21 @@ extension SSGC.ModuleIndex
         let phylum:Phylum.Decl
         public
         let path:UnqualifiedPath
+        public
+        let documented:Bool
 
-        init(phylum:Phylum.Decl, path:UnqualifiedPath)
+        init(phylum:Phylum.Decl, path:UnqualifiedPath, documented:Bool)
         {
             self.phylum = phylum
             self.path = path
+            self.documented = documented
         }
     }
 }
 extension SSGC.ModuleIndex.Feature
 {
     init(from decl:borrowing SSGC.Decl)
     {
-        self.init(phylum: decl.phylum, path: decl.path)
+        self.init(phylum: decl.phylum, path: decl.path, documented: decl.comment != nil)
     }
 }

Sources/SymbolGraphCompiler/UCF.VerticalOverload (ext).swift renamed to Sources/SymbolGraphCompiler/UCF.CausalOverload (ext).swift

@@ -9,14 +9,16 @@ extension UCF.CausalOverload
         .init(phylum: decl.phylum,
             decl: decl.id,
             heir: heir,
-            hash: .decl(.init(decl.id, self: heir)))
+            hash: .decl(.init(decl.id, self: heir)),
+            documented: decl.comment != nil)
     }
     static
     func decl(_ decl:SSGC.Decl) -> Self
     {
         .init(phylum: decl.phylum,
             decl: decl.id,
             heir: nil,
-            hash: .decl(decl.id))
+            hash: .decl(decl.id),
+            documented: decl.comment != nil)
     }
 }

Sources/SymbolGraphLinker/SSGC.Linker.swift

@@ -215,7 +215,7 @@ extension SSGC.Linker
                 declarations,
                 destinations)
             {
-                for (i, decl) in zip(destination.range, namespace.decls)
+                for (i, decl):(Int32, SSGC.Decl) in zip(destination.range, namespace.decls)
                 {
                     let hash:FNV24 = .decl(decl.id)
                     //  Make the decl visible to codelink resolution.
@@ -224,6 +224,7 @@ extension SSGC.Linker
                         decl: i,
                         heir: nil,
                         hash: hash,
+                        documented: decl.comment != nil,
                         id: decl.id))
                     //  Assign the decl a URI, and record the decl’s hash
                     //  so we will know if it has a hash collision.
@@ -306,6 +307,7 @@ extension SSGC.Linker
                     decl: f,
                     heir: extendee,
                     hash: .decl(.init(id, self: $0.extendee.id)),
+                    documented: feature.documented,
                     id: id)
 
                 self.tables.packageLinks[namespace, $0.extendee.path, feature.path.last]

Sources/SymbolGraphLinkerTests/Main.LinkResolution.swift

@@ -32,13 +32,15 @@ extension Main.LinkResolution:TestBattery
                 decl: 0,
                 heir: nil,
                 hash: .init(hashing: "x"),
+                documented: true,
                 id: "x"))
 
             tables.packageLinks["ThisModule", .init(["A"], "c")].append(.init(
                 phylum: .func(.instance),
                 decl: 1,
                 heir: nil,
                 hash: .init(hashing: "y"),
+                documented: true,
                 id: "y"))
 
             if  let tests:TestGroup = tests / "Unscoped"
@@ -92,13 +94,15 @@ extension Main.LinkResolution:TestBattery
                 decl: 0,
                 heir: nil,
                 hash: .init(hashing: "x"),
+                documented: true,
                 id: "x"))
 
             tables.packageLinks["OtherModule", .init(["A"], "c")].append(.init(
                 phylum: .func(.instance),
                 decl: 1,
                 heir: nil,
                 hash: .init(hashing: "y"),
+                documented: true,
                 id: "y"))
 
             if  let tests:TestGroup = tests / "Unscoped"

Sources/SymbolGraphs/SymbolGraphABI.swift

@@ -3,5 +3,5 @@ import SemanticVersions
 @frozen public
 enum SymbolGraphABI
 {
-    @inlinable public static var version:PatchVersion { .v(0, 12, 1) }
+    @inlinable public static var version:PatchVersion { .v(0, 12, 2) }
 }