add help article about mangled names

Author: tayloraswift

Sources/Swiftinit/Swiftinit.Root.swift

@@ -11,6 +11,7 @@ extension Swiftinit
         case blog
         case docs
         case docc
+        case help
         case hist
         case login
         case lunr
@@ -53,6 +54,7 @@ extension Swiftinit.Root:Identifiable
         case .blog:         "articles"
         case .docs:         "docs"
         case .docc:         "docc"
+        case .help:         "help"
         case .hist:         "hist"
         case .login:        "login"
         case .lunr:         "lunr"

Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Blog.Article.swift renamed to Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Blog.ArticlePage.swift

@@ -28,7 +28,12 @@ extension Swiftinit.Blog.ArticlePage
 }
 extension Swiftinit.Blog.ArticlePage:Swiftinit.RenderablePage
 {
-    var title:String { "\(self.volume.title) Documentation" }
+    var title:String { "\(self.vertex.headline.safe)" }
+
+    var description:String?
+    {
+        self.vertex.overview.map { "\(self.context.prose($0.markdown))" }
+    }
 }
 extension Swiftinit.Blog.ArticlePage:Swiftinit.StaticPage
 {

Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.DeclPage.swift

@@ -221,6 +221,14 @@ extension Swiftinit.Docs.DeclPage:Swiftinit.VertexPage
                 $0[.p, { $0.class = "symbol" }]
                 {
                     $0[.code] = self.vertex.symbol.rawValue
+
+                    $0[.span, { $0.class = "parenthetical" }]
+                    {
+                        $0[.a]
+                        {
+                            $0.href = "/help/what-are-mangled-names"
+                        } = "What are these?"
+                    }
                 }
 
                 $0[.p]

Sources/SwiftinitServer/Server/Swiftinit.ClientAnnotation.swift

@@ -1,4 +1,5 @@
 import HTTP
+import HTTPServer
 import IP
 import UA
 import UnidocProfiling
@@ -71,11 +72,7 @@ extension Swiftinit.ClientAnnotation
         }
 
         if  case "*"? = headers.acceptLanguage,
-            agent == """
-            Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) \
-            AppleWebKit/605.1.15 (KHTML, like Gecko) \
-            Version/14.0 Safari/605.1.15
-            """
+            agent.starts(with: "Discourse Forum Onebox")
         {
             // This is *probably* the Swift Forums bot.
             return .robot(.discoursebot)

Sources/SwiftinitServer/Swiftinit.AnyEndpoint.swift

@@ -145,12 +145,13 @@ extension Swiftinit.AnyEndpoint
     }
 
     static
-    func get(articles trunk:String,
+    func get(blog:String,
+        _ trunk:String,
         with parameters:Swiftinit.PipelineParameters) -> Self
     {
         .explainable(Swiftinit.BlogEndpoint.init(query: .init(
                 volume: .init(package: "__swiftinit", version: "__max"),
-                vertex: .init(path: ["Articles", trunk], hash: nil))),
+                vertex: .init(path: [blog, trunk], hash: nil))),
             parameters: parameters)
     }
 

Sources/SwiftinitServer/Swiftinit.IntegralRequest.Metadata.swift

@@ -1,4 +1,5 @@
 import HTTP
+import HTTPServer
 import IP
 import NIOHPACK
 import NIOHTTP1
@@ -19,6 +20,7 @@ extension Swiftinit.IntegralRequest
         let service:IP.Service?
         let path:String
 
+        private
         init(
             annotation:Swiftinit.ClientAnnotation,
             cookies:Swiftinit.Cookies,
@@ -97,5 +99,14 @@ extension Swiftinit.IntegralRequest.Metadata
             address: address,
             service: service,
             path: path)
+
+        if  case .robot(.discoursebot) = self.annotation
+        {
+            Log[.debug] = """
+            Approved possible Swift Forums robot
+                User-Agent: '\(headers.userAgent ?? "")'
+                IP Address: \(address)
+            """
+        }
     }
 }

Sources/SwiftinitServer/Swiftinit.IntegralRequest.swift

@@ -198,13 +198,17 @@ extension Swiftinit.IntegralRequest
                 with: .init(uri.query?.parameters))
 
         case Swiftinit.Root.blog.id:
-            endpoint = .get(articles: trunk,
+            endpoint = .get(blog: "Articles", trunk,
                 with: .init(uri.query?.parameters, tag: tag))
 
         case Swiftinit.Root.docs.id, Swiftinit.Root.docc.id, Swiftinit.Root.hist.id:
             endpoint = .get(docs: trunk, path,
                 with: .init(uri.query?.parameters, tag: tag))
 
+        case Swiftinit.Root.help.id:
+            endpoint = .get(blog: "Help", trunk,
+                with: .init(uri.query?.parameters, tag: tag))
+
         case Swiftinit.Root.lunr.id:
             endpoint = .get(lunr: trunk,
                 with: .init(uri.query?.parameters, tag: tag))

Sources/UnidocLinker/Resolver/Unidoc.Resolver.swift

@@ -189,7 +189,11 @@ extension Unidoc.Resolver
                 return .text(unresolved.link)
             }
 
-            let text:String = codelink.path.visible.joined(separator: ".")
+            /// This looks a lot like a stem, but it always uses spaces, never tabs.
+            /// Its purpose is to allow splitting the path into words without parsing the
+            /// Swift language grammar.
+            var path:String { codelink.path.visible.joined(separator: " ") }
+            var text:String { codelink.path.visible.joined(separator: ".") }
             let length:Int = codelink.path.visible.count
 
             switch resolution
@@ -198,10 +202,10 @@ extension Unidoc.Resolver
                 return .text(text)
 
             case .scalar(let scalar)?:
-                return .path(text, self.context.expand(scalar, to: length))
+                return .path(path, self.context.expand(scalar, to: length))
 
             case .vector(let feature, self: let heir)?:
-                return .path(text, self.context.expand((heir, feature), to: length))
+                return .path(path, self.context.expand((heir, feature), to: length))
             }
         }
 

TestPackages/__swiftinit/Package.swift

@@ -5,8 +5,10 @@ let package:Package = .init(name: "Swiftinit",
     products:
     [
         .library(name: "Articles", targets: ["Articles"]),
+        .library(name: "Help", targets: ["Help"]),
     ],
     targets:
     [
-        .target(name: "Articles", exclude: ["md"]),
+        .target(name: "Articles"),
+        .target(name: "Help"),
     ])