BridgeJS: Include Swift doc comments in generated d.ts

Propagate Swift `///` and `/** */` documentation on exported declarations
into the generated TypeScript declarations as JSDoc, so editors surface
hover docs for the bridged API.

The exporter now captures the leading doc comment for functions, classes,
methods, properties, constructors, structs, and enums into the skeleton,
and the linker renders it as a single JSDoc block. The Swift DocC field
list is mapped as the inverse of the TS2Swift importer: the leading
description becomes the JSDoc body, `- Parameters:`/`- Parameter x:` become
`@param`, `- Returns:` becomes `@returns`, and `- Throws:` becomes
`@throws`. Existing default-value annotations are merged into the same
block so a parameter never emits two comment blocks; declarations without
doc comments produce byte-identical output to before.

Author: krodak

Examples/PlayBridgeJS/Sources/PlayBridgeJS/Generated/JavaScript/BridgeJS.json

@@ -16,6 +16,7 @@
         "methods" : [
           {
             "abiName" : "bjs_PlayBridgeJS_updateDetailed",
+            "documentation" : "Structured entry point used by the playground so JS doesn't need to parse diagnostics.",
             "effects" : {
               "isAsync" : false,
               "isStatic" : false,

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -1266,10 +1266,54 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             returnType: returnType,
             effects: effects,
             namespace: finalNamespace,
-            staticContext: staticContext
+            staticContext: staticContext,
+            documentation: extractDocumentation(from: node)
         )
     }
 
+    /// Returns the doc comment (`///` or `/** */`) attached to a declaration, with
+    /// markers stripped and DocC field lists (`- Parameters:`, `- Returns:`) preserved.
+    private func extractDocumentation(from node: some SyntaxProtocol) -> String? {
+        var run: [String] = []
+        for piece in node.leadingTrivia {
+            switch piece {
+            case .docLineComment(let text):
+                var line = Substring(text)
+                if line.hasPrefix("///") { line = line.dropFirst(3) }
+                if line.first == " " { line = line.dropFirst() }
+                run.append(String(line))
+            case .docBlockComment(let text):
+                run.append(contentsOf: stripBlockComment(text))
+            case .newlines(let count), .carriageReturns(let count), .carriageReturnLineFeeds(let count):
+                if count >= 2 { run.removeAll() }
+            case .lineComment, .blockComment:
+                run.removeAll()
+            default:
+                continue
+            }
+        }
+        let joined = run.joined(separator: "\n")
+        return joined.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? nil : joined
+    }
+
+    private func stripBlockComment(_ text: String) -> [String] {
+        var body = Substring(text)
+        if body.hasPrefix("/**") { body = body.dropFirst(3) }
+        if body.hasSuffix("*/") { body = body.dropLast(2) }
+        var lines = body.split(separator: "\n", omittingEmptySubsequences: false).map { raw -> String in
+            var line = raw[...]
+            while let first = line.first, first == " " || first == "\t" { line = line.dropFirst() }
+            if line.first == "*" {
+                line = line.dropFirst()
+                if line.first == " " { line = line.dropFirst() }
+            }
+            return String(line)
+        }
+        while lines.first?.trimmingCharacters(in: .whitespaces).isEmpty == true { lines.removeFirst() }
+        while lines.last?.trimmingCharacters(in: .whitespaces).isEmpty == true { lines.removeLast() }
+        return lines
+    }
+
     private func collectEffects(signature: FunctionSignatureSyntax, isStatic: Bool = false) -> Effects? {
         let isAsync = signature.effectSpecifiers?.asyncSpecifier != nil
         var isThrows = false
@@ -1360,7 +1404,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             let constructor = ExportedConstructor(
                 abiName: "bjs_\(classAbiName)_init",
                 parameters: parameters,
-                effects: effects
+                effects: effects,
+                documentation: extractDocumentation(from: node)
             )
             exportedClassByName[classKey]?.constructor = constructor
 
@@ -1383,7 +1428,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             let constructor = ExportedConstructor(
                 abiName: "bjs_\(structAbiName)_init",
                 parameters: parameters,
-                effects: effects
+                effects: effects,
+                documentation: extractDocumentation(from: node)
             )
             exportedStructByName[structKey]?.constructor = constructor
 
@@ -1490,7 +1536,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
                 isReadonly: isReadonly,
                 isStatic: isStatic,
                 namespace: finalNamespace,
-                staticContext: staticContext
+                staticContext: staticContext,
+                documentation: extractDocumentation(from: node)
             )
 
             if case .enumBody(_, let key) = state {
@@ -1537,7 +1584,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             methods: [],
             properties: [],
             namespace: effectiveNamespace,
-            identityMode: classIdentityMode
+            identityMode: classIdentityMode,
+            documentation: extractDocumentation(from: node)
         )
         let uniqueKey = makeKey(name: name, namespace: effectiveNamespace)
 
@@ -1657,7 +1705,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             namespace: effectiveNamespace,
             emitStyle: emitStyle,
             staticMethods: [],
-            staticProperties: []
+            staticProperties: [],
+            documentation: extractDocumentation(from: node)
         )
 
         let enumUniqueKey = makeKey(name: name, namespace: effectiveNamespace)
@@ -1774,7 +1823,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             name: name,
             methods: [],
             properties: [],
-            namespace: effectiveNamespace
+            namespace: effectiveNamespace,
+            documentation: extractDocumentation(from: node)
         )
 
         stateStack.push(state: .protocolBody(name: name, key: protocolUniqueKey))
@@ -1798,7 +1848,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             name: name,
             methods: methods,
             properties: exportedProtocolByName[protocolUniqueKey]?.properties ?? [],
-            namespace: effectiveNamespace
+            namespace: effectiveNamespace,
+            documentation: extractDocumentation(from: node)
         )
 
         exportedProtocolByName[protocolUniqueKey] = exportedProtocol
@@ -1874,7 +1925,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
                         isReadonly: true,
                         isStatic: false,
                         namespace: effectiveNamespace,
-                        staticContext: nil
+                        staticContext: nil,
+                        documentation: extractDocumentation(from: varDecl)
                     )
                     properties.append(property)
                 }
@@ -1888,7 +1940,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             explicitAccessControl: explicitAccessControl,
             properties: properties,
             methods: [],
-            namespace: effectiveNamespace
+            namespace: effectiveNamespace,
+            documentation: extractDocumentation(from: node)
         )
 
         exportedStructByName[structUniqueKey] = exportedStruct
@@ -1981,7 +2034,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             returnType: returnType,
             effects: effects,
             namespace: namespace,
-            staticContext: nil
+            staticContext: nil,
+            documentation: extractDocumentation(from: node)
         )
     }
 
@@ -2022,7 +2076,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             let exportedProperty = ExportedProtocolProperty(
                 name: propertyName,
                 type: propertyType,
-                isReadonly: isReadonly
+                isReadonly: isReadonly,
+                documentation: extractDocumentation(from: node)
             )
 
             if var currentProtocol = exportedProtocolByName[protocolKey] {
@@ -2033,7 +2088,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
                     name: currentProtocol.name,
                     methods: currentProtocol.methods,
                     properties: properties,
-                    namespace: currentProtocol.namespace
+                    namespace: currentProtocol.namespace,
+                    documentation: currentProtocol.documentation
                 )
                 exportedProtocolByName[protocolKey] = currentProtocol
             }