Merge pull request #9 from tayloraswift/availability-badges

tayloraswift · web-flow · commit 4cd80a7ef2bd · 2023-08-28T21:01:54.000-05:00
Availability badges
diff --git a/Assets/css/Main.css b/Assets/css/Main.css
diff --git a/Assets/css/Main.css.map b/Assets/css/Main.css.map
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <div align="center">
 
-<strong><em><code>unidoc</code></em></strong><br><small><code>0.1.0</code></small>
+<strong><em><code>unidoc</code></em></strong><br><small><code>0.1.3</code></small>
 
 [![ci build status](https://github.com/kelvin13/swift-unidoc/actions/workflows/build.yml/badge.svg)](https://github.com/kelvin13/swift-unidoc/actions/workflows/build.yml)
 
diff --git a/Sources/Availability/Domains/Availability.PlatformDomain.swift b/Sources/Availability/Domains/Availability.PlatformDomain.swift
@@ -3,15 +3,15 @@ import SemanticVersions
 extension Availability
 {
     @frozen public
-    enum PlatformDomain:String, CaseIterable, Hashable, Sendable
+    enum PlatformDomain:String, CaseIterable, Equatable, Hashable, Sendable
     {
         case iOS
         case macOS
         case macCatalyst
+        case openBSD    = "OpenBSD"
         case tvOS
         case watchOS
         case windows    = "Windows"
-        case openBSD    = "OpenBSD"
 
         case iOSApplicationExtension
         case macOSApplicationExtension
@@ -29,3 +29,25 @@ extension Availability.PlatformDomain:AvailabilityDomain
     public
     typealias Unavailability = Availability.EternalRange
 }
+extension Availability.PlatformDomain:CustomStringConvertible
+{
+    @inlinable public
+    var description:String
+    {
+        switch self
+        {
+        case .iOS:                              return "iOS"
+        case .macOS:                            return "macOS"
+        case .macCatalyst:                      return "Mac Catalyst"
+        case .openBSD:                          return "OpenBSD"
+        case .tvOS:                             return "tvOS"
+        case .watchOS:                          return "watchOS"
+        case .windows:                          return "Windows"
+        case .iOSApplicationExtension:          return "iOS App Extension"
+        case .macOSApplicationExtension:        return "macOS App Extension"
+        case .macCatalystApplicationExtension:  return "Mac Catalyst App Extension"
+        case .tvOSApplicationExtension:         return "tvOS App Extension"
+        case .watchOSApplicationExtension:      return "watchOS App Extension"
+        }
+    }
+}
diff --git a/Sources/SymbolGraphParts/Availability/Availability (ext).swift b/Sources/SymbolGraphParts/Availability/Availability (ext).swift
@@ -45,7 +45,8 @@ extension Availability:JSONDecodable
                     message: message)
 
             case .platform(let domain):
-                let deprecated:Availability.AnyRange? = try json[.isUnconditionallyDeprecated]?.decode(
+                let deprecated:Availability.AnyRange? =
+                    try json[.isUnconditionallyDeprecated]?.decode(
                         as: Bool.self)
                     {
                         $0 ? .unconditionally : nil
diff --git a/Sources/UnidocLinker/Groups/DynamicContext.SortPriority.Phylum.swift b/Sources/UnidocLinker/Groups/DynamicContext.SortPriority.Phylum.swift
@@ -1,9 +1,10 @@
+
 import Sources
 import Unidoc
 
-extension DynamicContext
+extension DynamicContext.SortPriority
 {
-    enum SortLeague:Equatable, Comparable
+    enum Phylum:Equatable, Comparable
     {
         case `var`
         case `func`
@@ -27,7 +28,7 @@ extension DynamicContext
         case  method(Unidoc.Decl.Objectivity)
     }
 }
-extension DynamicContext.SortLeague
+extension DynamicContext.SortPriority.Phylum
 {
     init(_ phylum:Unidoc.Decl, position:SourcePosition? = nil)
     {
diff --git a/Sources/UnidocLinker/Groups/DynamicContext.SortPriority.swift b/Sources/UnidocLinker/Groups/DynamicContext.SortPriority.swift
@@ -0,0 +1,8 @@
+extension DynamicContext
+{
+    enum SortPriority:Equatable, Comparable
+    {
+        case available  (Phylum, String, Int32)
+        case removed    (Phylum, String, Int32)
+    }
+}
diff --git a/Sources/UnidocLinker/Groups/DynamicContext.swift b/Sources/UnidocLinker/Groups/DynamicContext.swift
@@ -233,7 +233,7 @@ extension DynamicContext
 extension DynamicContext
 {
     /// Get the sort-priority of a declaration.
-    func priority(of decl:Unidoc.Scalar) -> (SortLeague, String, Int32)?
+    func priority(of decl:Unidoc.Scalar) -> SortPriority?
     {
         self[decl.package]?.priority(of: decl)
     }
diff --git a/Sources/UnidocLinker/Snapshots/SnapshotObject.swift b/Sources/UnidocLinker/Snapshots/SnapshotObject.swift
@@ -80,14 +80,16 @@ extension SnapshotObject
 }
 extension SnapshotObject
 {
-    func priority(of decl:Unidoc.Scalar) -> (DynamicContext.SortLeague, String, Int32)?
+    func priority(of decl:Unidoc.Scalar) -> DynamicContext.SortPriority?
     {
         if  let local:Int32 = decl - self.zone,
             let decl:SymbolGraph.Decl = snapshot.graph.decls[local]?.decl
         {
-            let league:DynamicContext.SortLeague = .init(decl.phylum,
+            let phylum:DynamicContext.SortPriority.Phylum = .init(decl.phylum,
                 position: decl.location?.position)
-            return (league, decl.path.last, local)
+            return decl.signature.availability.isGenerallyRecommended ?
+                .available(phylum, decl.path.last, local) :
+                .removed(phylum, decl.path.last, local)
         }
         else
         {
diff --git a/Sources/UnidocPages/Groups/Inliner.Groups.Genericness.swift b/Sources/UnidocPages/Groups/Inliner.Groups.Genericness.swift
@@ -2,7 +2,11 @@ extension Inliner.Groups
 {
     enum Genericness:Equatable, Hashable, Comparable, Sendable
     {
-        case generic
-        case concrete
+        /// No generic constraints.
+        case unconstrained
+        /// At least one generic constraint, but not enough to fully concretize the extension.
+        case constrained
+        /// Enough generic constraints to fully concretize the extension.
+        case concretized
     }
 }
diff --git a/Sources/UnidocPages/Groups/Inliner.Groups.Generics.swift b/Sources/UnidocPages/Groups/Inliner.Groups.Generics.swift
@@ -23,6 +23,8 @@ extension Inliner.Groups.Generics
         self.init(parameters: generics.reduce(into: []) { $0.insert($1.name) })
     }
 
+    var count:Int { self.parameters.count }
+
     /// Returns the number of free generic parameters remaining after applying any same-type
     /// constraints in the given list.
     func count(substituting constraints:[GenericConstraint<Unidoc.Scalar?>]) -> Int
diff --git a/Sources/UnidocPages/Groups/Inliner.Groups.swift b/Sources/UnidocPages/Groups/Inliner.Groups.swift
@@ -77,8 +77,10 @@ extension Inliner.Groups
                     .third($0.package)
                 } ?? .first
 
-                let genericness:Genericness =
-                    generics.count(substituting: group.conditions) == 0 ? .generic : .concrete
+                let genericness:Genericness = group.conditions.isEmpty ?
+                    .unconstrained : generics.count(substituting: group.conditions) > 0 ?
+                    .constrained :
+                    .concretized
 
                 extensions.append((group, partisanship, genericness))
 
diff --git a/Sources/UnidocPages/Inlining/Inliner.Card.swift b/Sources/UnidocPages/Inlining/Inliner.Card.swift
@@ -49,7 +49,10 @@ extension Inliner.Card:HyperTextOutputStreamable
         case .decl(let master):
             html[.li, { $0.class = "decl" }]
             {
-                $0[link: self.target] = master.signature.abridged
+                let style:String? = master.signature.availability.isGenerallyRecommended ?
+                    nil : "not-recommended"
+
+                $0[link: self.target] { $0.class = style } = master.signature.abridged
                 $0 ?= self.overview
             }
 
diff --git a/Sources/UnidocPages/Templates/Site.Docs.Decl.swift b/Sources/UnidocPages/Templates/Site.Docs.Decl.swift
@@ -1,3 +1,4 @@
+import Availability
 import HTML
 import LexicalPaths
 import ModuleGraphs
@@ -115,6 +116,41 @@ extension Site.Docs.Decl:ApplicationPage
             }
         }
 
+        let availability:Availability = self.master.signature.availability
+        if  let notice:String = availability.notice
+        {
+            main[.section, { $0.class = "deprecation" }] { $0[.p] = notice }
+        }
+        else if !availability.isEmpty
+        {
+            main[.section, { $0.class = "availability" }]
+            {
+                $0[.dl]
+                {
+                    if  let badge:String = availability.agnostic[.swift]?.badge
+                    {
+                        $0[.dt] = "Swift"
+                        $0[.dd] = badge
+                    }
+                    if  let badge:String = availability.agnostic[.swiftPM]?.badge
+                    {
+                        $0[.dt] = "SwiftPM"
+                        $0[.dd] = badge
+                    }
+
+                    for platform:Availability.PlatformDomain in
+                        Availability.PlatformDomain.allCases
+                    {
+                        if  let badge:String = availability.platforms[platform]?.badge
+                        {
+                            $0[.dt] = "\(platform)"
+                            $0[.dd] = badge
+                        }
+                    }
+                }
+            }
+        }
+
         main[.section, { $0.class = "declaration" }]
         {
             $0[.pre]
diff --git a/Sources/UnidocPages/UI/Availability (ext).swift b/Sources/UnidocPages/UI/Availability (ext).swift
@@ -0,0 +1,11 @@
+import Availability
+
+extension Availability
+{
+    var notice:String?
+    {
+        self.universal?.notice ??
+        self.agnostic[.swift]?.notice("Swift") ??
+        self.agnostic[.swiftPM]?.notice("SwiftPM")
+    }
+}
diff --git a/Sources/UnidocPages/UI/Availability.Clauses (ext).swift b/Sources/UnidocPages/UI/Availability.Clauses (ext).swift
@@ -0,0 +1,97 @@
+import Availability
+
+extension Availability.Clauses<Availability.UniversalDomain>
+{
+    var notice:String?
+    {
+        guard case .unconditionally? = self.deprecated
+        else
+        {
+            return nil
+        }
+        if  let name:String = self.renamed
+        {
+            return "This declaration is deprecated. It has been renamed to \(name)."
+        }
+        else if
+            let message:String = self.message
+        {
+            return "This declaration is deprecated: \(message)"
+        }
+        else
+        {
+            return "This declaration is deprecated."
+        }
+    }
+}
+extension Availability.Clauses<Availability.AgnosticDomain>
+{
+    func notice(_ tool:String) -> String?
+    {
+        var prose:String
+        switch (obsoleted: self.obsoleted, deprecated: self.deprecated)
+        {
+        case (obsoleted: let version?, _):
+            prose = "This declaration was obsoleted in \(tool) \(version)"
+
+        case (nil, deprecated: .since(let version?)?):
+            prose = "This declaration was deprecated in \(tool) \(version)"
+
+        case (nil, deprecated: .since(nil)?):
+            prose = "This declaration is deprecated"
+
+        case (nil, nil):
+            return nil
+        }
+
+        if  let name:String = self.renamed
+        {
+            prose += ". It has been renamed to \(name)."
+        }
+        else if
+            let message:String = self.message
+        {
+            prose += ": \(message)"
+        }
+        else
+        {
+            prose += "."
+        }
+
+        return prose
+    }
+
+    var badge:String?
+    {
+        self.introduced.map { "\($0)+" }
+    }
+}
+extension Availability.Clauses<Availability.PlatformDomain>
+{
+    var badge:String?
+    {
+        switch
+        (
+            unavailable: self.unavailable,
+            deprecated: self.deprecated,
+            obsoleted: self.obsoleted,
+            introduced: self.introduced
+        )
+        {
+        case (unavailable: .unconditionally?, _, _, _):
+            return "unavailable"
+
+        case (nil, deprecated: _?, _, _):
+            return "deprecated"
+
+        case (nil, nil, obsoleted: _?, _):
+            return "obsoleted"
+
+        case (nil, nil, nil, introduced: let version?):
+            return "\(version)+"
+
+        case (nil, nil, nil, nil):
+            return nil
+        }
+    }
+}
diff --git a/Stylesheets/_Colors.scss b/Stylesheets/_Colors.scss
@@ -3,6 +3,12 @@ $light-background-pink: rgb(255, 224, 239);
 $light-foreground: rgb(22, 22, 22);
 $light-foreground-semi: rgb(109, 109, 109);
 
+$light-foreground-elevated: rgb(223, 223, 223);
+$light-foreground-elevated-shadow: rgb(172, 172, 172);
+
+$light-coral-elevated: rgb(255, 103, 103);
+$light-coral-elevated-shadow: rgb(235, 75, 75);
+
 $light-code-well: rgb(233, 233, 233);
 $light-snippet-line-number: rgb(192, 192, 192);
 
diff --git a/Stylesheets/_Declarations.scss b/Stylesheets/_Declarations.scss
diff --git a/Stylesheets/_Groups.scss b/Stylesheets/_Groups.scss
diff --git a/Stylesheets/_Prose.scss b/Stylesheets/_Prose.scss

Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,8 @@ extension Availability:JSONDecodable`
`45`	`45`	`message: message)`
`46`	`46`
`47`	`47`	`case .platform(let domain):`
`48`		`- let deprecated:Availability.AnyRange? = try json[.isUnconditionallyDeprecated]?.decode(`
	`48`	`+ let deprecated:Availability.AnyRange? =`
	`49`	`+ try json[.isUnconditionallyDeprecated]?.decode(`
`49`	`50`	`as: Bool.self)`
`50`	`51`	`{`
`51`	`52`	`$0 ? .unconditionally : nil`
Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,10 @@`
	`1`	`+`
`1`	`2`	`import Sources`
`2`	`3`	`import Unidoc`
`3`	`4`
`4`		`-extension DynamicContext`
	`5`	`+extension DynamicContext.SortPriority`
`5`	`6`	`{`
`6`		`- enum SortLeague:Equatable, Comparable`
	`7`	`+ enum Phylum:Equatable, Comparable`
`7`	`8`	`{`
`8`	`9`	case `var`
`9`	`10`	case `func`
`@@ -27,7 +28,7 @@ extension DynamicContext`
`27`	`28`	`case method(Unidoc.Decl.Objectivity)`
`28`	`29`	`}`
`29`	`30`	`}`
`30`		`-extension DynamicContext.SortLeague`
	`31`	`+extension DynamicContext.SortPriority.Phylum`
`31`	`32`	`{`
`32`	`33`	`init(_ phylum:Unidoc.Decl, position:SourcePosition? = nil)`
`33`	`34`	`{`
Original file line number	Diff line number	Diff line change
`@@ -233,7 +233,7 @@ extension DynamicContext`
`233`	`233`	`extension DynamicContext`
`234`	`234`	`{`
`235`	`235`	`/// Get the sort-priority of a declaration.`
`236`		`- func priority(of decl:Unidoc.Scalar) -> (SortLeague, String, Int32)?`
	`236`	`+ func priority(of decl:Unidoc.Scalar) -> SortPriority?`
`237`	`237`	`{`
`238`	`238`	`self[decl.package]?.priority(of: decl)`
`239`	`239`	`}`
Original file line number	Diff line number	Diff line change
`@@ -80,14 +80,16 @@ extension SnapshotObject`
`80`	`80`	`}`
`81`	`81`	`extension SnapshotObject`
`82`	`82`	`{`
`83`		`- func priority(of decl:Unidoc.Scalar) -> (DynamicContext.SortLeague, String, Int32)?`
	`83`	`+ func priority(of decl:Unidoc.Scalar) -> DynamicContext.SortPriority?`
`84`	`84`	`{`
`85`	`85`	`if let local:Int32 = decl - self.zone,`
`86`	`86`	`let decl:SymbolGraph.Decl = snapshot.graph.decls[local]?.decl`
`87`	`87`	`{`
`88`		`- let league:DynamicContext.SortLeague = .init(decl.phylum,`
	`88`	`+ let phylum:DynamicContext.SortPriority.Phylum = .init(decl.phylum,`
`89`	`89`	`position: decl.location?.position)`
`90`		`- return (league, decl.path.last, local)`
	`90`	`+ return decl.signature.availability.isGenerallyRecommended ?`
	`91`	`+ .available(phylum, decl.path.last, local) :`
	`92`	`+ .removed(phylum, decl.path.last, local)`
`91`	`93`	`}`
`92`	`94`	`else`
`93`	`95`	`{`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,11 @@ extension Inliner.Groups`
`2`	`2`	`{`
`3`	`3`	`enum Genericness:Equatable, Hashable, Comparable, Sendable`
`4`	`4`	`{`
`5`		`- case generic`
`6`		`- case concrete`
	`5`	`+ /// No generic constraints.`
	`6`	`+ case unconstrained`
	`7`	`+ /// At least one generic constraint, but not enough to fully concretize the extension.`
	`8`	`+ case constrained`
	`9`	`+ /// Enough generic constraints to fully concretize the extension.`
	`10`	`+ case concretized`
`7`	`11`	`}`
`8`	`12`	`}`