Distinguish operators from function implementations

Author: mattt

Sources/SwiftDoc/Extensions/SwiftSemantics+Extensions.swift

@@ -27,3 +27,18 @@ extension Structure: Type {}
 extension Unknown: Type {
     public var inheritance: [String] { return [] }
 }
+
+// MARK: -
+
+extension Operator.Kind: Comparable {
+    public static func < (lhs: Operator.Kind, rhs: Operator.Kind) -> Bool {
+        switch (lhs, rhs) {
+        case (_, .infix):
+            return true
+        case (.postfix, _):
+            return true
+        default:
+            return false
+        }
+    }
+}

Sources/SwiftDoc/Helpers.swift

@@ -6,6 +6,7 @@ public func route(for symbol: Symbol) -> String {
 
 public func route(for name: CustomStringConvertible) -> String {
     return name.description.replacingOccurrences(of: ".", with: "_")
+                           .replacingOccurrences(of: " ", with: "-")
 }
 
 public func path(for symbol: Symbol, with baseURL: String) -> String {

Sources/SwiftDoc/Interface.swift

@@ -12,7 +12,18 @@ public final class Interface {
 
         self.symbolsGroupedByIdentifier = Dictionary(grouping: symbols, by: { $0.id })
         self.symbolsGroupedByQualifiedName = Dictionary(grouping: symbols, by: { $0.id.description })
-        self.topLevelSymbols = symbols.filter { $0.api is Type || $0.id.pathComponents.isEmpty }
+
+        self.topLevelSymbols = symbols.filter { symbol in
+            if symbol.api is Type || symbol.api is Operator {
+                return true
+            }
+
+            if let function = symbol.api as? Function, function.isOperator {
+                return false
+            }
+
+            return symbol.id.pathComponents.isEmpty
+        }
 
         self.relationships = {
             let extensionsByExtendedType: [String: [Extension]] = Dictionary(grouping: symbols.flatMap { $0.context.compactMap { $0 as? Extension } }, by: { $0.extendedType })
@@ -89,6 +100,20 @@ public final class Interface {
             return Array(relationships)
         }()
 
+        self.functionsByOperator = {
+            var functionsByOperator: [Symbol: Set<Symbol>] = [:]
+
+            let functionsGroupedByName = Dictionary(grouping: symbols.filter { $0.api is Function},
+                                                    by: { $0.api.name })
+
+            for `operator` in symbols.filter({ $0.api is Operator }) {
+                let functions = functionsGroupedByName[`operator`.name] ?? []
+                functionsByOperator[`operator`] = Set(functions)
+            }
+
+            return functionsByOperator
+        }()
+
         self.relationshipsBySubject = Dictionary(grouping: relationships, by: { $0.subject.id })
         self.relationshipsByObject = Dictionary(grouping: relationships, by: { $0.object.id })
     }
@@ -98,6 +123,7 @@ public final class Interface {
     public let symbolsGroupedByIdentifier: [Symbol.ID: [Symbol]]
     public let symbolsGroupedByQualifiedName: [String: [Symbol]]
     public let topLevelSymbols: [Symbol]
+    public var functionsByOperator: [Symbol: Set<Symbol>]
     public var baseClasses: [Symbol] {
         symbols.filter { $0.api is Class && typesInherited(by: $0).isEmpty }
     }
@@ -115,7 +141,6 @@ public final class Interface {
         }
 
         return classClusters
-
     }
 
     public let relationships: [Relationship]

Sources/SwiftDoc/SourceFile.swift

@@ -168,6 +168,11 @@ public struct SourceFile: Hashable, Codable {
             return .skipChildren
         }
 
+        override func visit(_ node: OperatorDeclSyntax) -> SyntaxVisitorContinueKind {
+            push(symbol(Operator.self, node))
+            return .skipChildren
+        }
+
         override func visit(_ node: PrecedenceGroupDeclSyntax) -> SyntaxVisitorContinueKind {
             push(symbol(PrecedenceGroup.self, node))
             return .skipChildren

Sources/SwiftDoc/Symbol.swift

@@ -27,8 +27,21 @@ public final class Symbol {
         return api.name
     }
 
+    public var kind: String {
+        switch api {
+        case let function as Function where function.isOperator:
+            return "Operator"
+        default:
+            return String(describing: type(of: api))
+        }
+    }
+
     public private(set) lazy var id: ID = {
-        Identifier(pathComponents: context.compactMap {
+        if let `operator` = api as? Operator, `operator`.kind != .infix {
+            return Identifier(pathComponents: [], name: "\(`operator`.kind) \(`operator`.name)")
+        }
+
+        return Identifier(pathComponents: context.compactMap {
             ($0 as? Symbol)?.name ?? ($0 as? Extension)?.extendedType
         }, name: name)
     }()
@@ -38,6 +51,10 @@ public final class Symbol {
             return true
         }
 
+        if api is Operator {
+            return true
+        }
+
         if api.modifiers.contains(where: { $0.name == "public" || $0.name == "open" }) {
             return true
         }

Sources/swift-doc/Subcommands/Generate.swift

@@ -66,6 +66,8 @@ extension SwiftDoc {
             pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL, includingChildren: symbolFilter)
           case let `typealias` as Typealias:
             pages[route(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL)
+          case is Operator:
+            pages[route(for: symbol)] = OperatorPage(module: module, symbol: symbol, baseURL: baseURL)
           case let function as Function where !function.isOperator:
             globals[function.name, default: []] += [symbol]
           case let variable as Variable:

Sources/swift-doc/Supporting Types/Components/OperatorImplementations.swift

@@ -0,0 +1,96 @@
+import CommonMarkBuilder
+import SwiftDoc
+import SwiftMarkup
+import SwiftSemantics
+import HypertextLiteral
+
+struct OperatorImplementations: Component {
+    var symbol: Symbol
+    var module: Module
+    let baseURL: String
+
+    var implementations: [Symbol]
+
+    init(of symbol: Symbol, in module: Module, baseURL: String, implementations: [Symbol]) {
+        self.symbol = symbol
+        self.module = module
+        self.baseURL = baseURL
+        self.implementations = implementations
+    }
+
+
+    // MARK: - Component
+
+    var fragment: Fragment {
+        guard !implementations.isEmpty else { return Fragment { "" } }
+
+        return Fragment {
+            ForEach(in: implementations) { implementation -> BlockConvertible in
+                Section {
+                    Heading { implementation.name }
+
+                    Documentation(for: implementation, in: module, baseURL: baseURL)
+                }
+            }
+        }
+    }
+
+    var html: HypertextLiteral.HTML {
+        let sections = implementations.compactMap { implementation -> HypertextLiteral.HTML? in
+            guard let `operator` = symbol.api as? Operator,
+                  let function = implementation.api as? Function
+            else { return nil }
+
+            let heading: String
+            switch `operator`.kind {
+            case .infix:
+                guard function.signature.input.count == 2,
+                      let lhs = function.signature.input.first,
+                      let rhs = function.signature.input.last
+                else {
+                  return nil
+                }
+
+                heading = [lhs.type, function.name, rhs.type, function.genericWhereClause].compactMap { $0 }.joined(separator: " ")
+            case .prefix:
+                guard function.signature.input.count == 2,
+                      let operand = function.signature.input.first
+                else {
+                  return nil
+                }
+                heading = [function.name, operand.type, function.genericWhereClause].compactMap { $0 }.joined(separator: " ")
+
+            case .postfix:
+                guard function.signature.input.count == 2,
+                      let operand = function.signature.input.first
+                else {
+                  return nil
+                }
+                heading = [operand.type, function.name, function.genericWhereClause].compactMap { $0 }.joined(separator: " ")
+            }
+
+            return #"""
+                   <section>
+                   <h3>\#(heading)</h3>
+                   \#(Documentation(for: implementation, in: module, baseURL: baseURL).html)
+                   </section>
+                   """#
+        }
+
+        guard !sections.isEmpty else { return "" }
+
+        return #"""
+            <section id="implementations">
+                <h2>Implementations</h2>
+                \#(sections)
+            </section>
+        """#
+    }
+}
+
+fileprivate extension Function {
+    var genericWhereClause: String? {
+        guard !genericRequirements.isEmpty else { return nil }
+        return "where \(genericRequirements.map { $0.description }.joined(separator: ", "))"
+    }
+}

Sources/swift-doc/Supporting Types/Pages/HomePage.swift

@@ -34,8 +34,6 @@ struct HomePage: Page {
                 globalTypealiases.append(symbol)
             case is Operator:
                 operators.append(symbol)
-            case let function as Function where function.isOperator:
-                operators.append(symbol)
             case is Function:
                 globalFunctions.append(symbol)
             case is Variable:
@@ -44,6 +42,18 @@ struct HomePage: Page {
                 continue
             }
         }
+
+        classes.sort()
+        enumerations.sort()
+        structures.sort()
+        protocols.sort()
+        globalTypealiases.sort()
+        operators.sort(by: { (lhs, rhs) in
+            guard let lo = lhs.api as? Operator, let ro = rhs.api as? Operator else { return false }
+            return (lo.kind, lo.name) > (ro.kind, ro.name)
+        })
+        globalFunctions.sort()
+        globalVariables.sort()
     }
 
     // MARK: - Page
@@ -57,15 +67,15 @@ struct HomePage: Page {
             ForEach(in: [
                 ("Types", classes + enumerations + structures),
                 ("Protocols", protocols),
-                ("Operators", operators),
                 ("Global Typealiases", globalTypealiases),
                 ("Global Functions", globalFunctions),
                 ("Global Variables", globalVariables),
+                ("Operators", operators),
             ]) { (heading, symbols) in
                 if (!symbols.isEmpty) {
                     Heading { heading }
 
-                    List(of: symbols.sorted()) { symbol in
+                    List(of: symbols) { symbol in
                         Abstract(for: symbol, baseURL: baseURL).fragment
                     }
                 }
@@ -82,15 +92,16 @@ struct HomePage: Page {
             ("Protocols", protocols),
             ("Typealiases", globalTypealiases),
             ("Functions", globalFunctions),
-            ("Variables", globalVariables)
+            ("Variables", globalVariables),
+            ("Operators", operators),
         ].compactMap { (heading, symbols) -> HypertextLiteral.HTML? in
             guard !symbols.isEmpty else { return nil }
 
             return #"""
             <section id=\#(heading.lowercased())>
                 <h2>\#(heading)</h2>
                 <dl>
-                    \#(symbols.sorted().map { Abstract(for: $0, baseURL: baseURL).html })
+                    \#(symbols.map { Abstract(for: $0, baseURL: baseURL).html })
                 </dl>
             </section>
         """#

Sources/swift-doc/Supporting Types/Pages/OperatorPage.swift

@@ -0,0 +1,46 @@
+import SwiftSemantics
+import SwiftDoc
+import CommonMarkBuilder
+import HypertextLiteral
+
+struct OperatorPage: Page {
+    let module: Module
+    let symbol: Symbol
+    let implementations: [Symbol]
+    let baseURL: String
+
+    init(module: Module, symbol: Symbol, baseURL: String) {
+        precondition(symbol.api is Operator)
+        self.module = module
+        self.symbol = symbol
+        self.implementations = module.interface.functionsByOperator[symbol]?.sorted() ?? []
+        self.baseURL = baseURL
+    }
+
+    // MARK: - Page
+
+    var title: String {
+        return symbol.id.description
+    }
+
+    var document: CommonMark.Document {
+        return CommonMark.Document {
+            Heading { symbol.id.description }
+
+            Documentation(for: symbol, in: module, baseURL: baseURL)
+        }
+    }
+
+    var html: HypertextLiteral.HTML {
+        return #"""
+        <h1>
+            <small>\#(symbol.kind)</small>
+            <code class="name">\#(softbreak(symbol.id.description))</code>
+        </h1>
+
+        \#(Documentation(for: symbol, in: module, baseURL: baseURL).html)
+        \#(OperatorImplementations(of: symbol, in: module, baseURL: baseURL, implementations: implementations).html)
+        """#
+    }
+}
+