◐ Shell
reader mode source ↗
Skip to content

BridgeJS: Generate Swift doc-comment based on JSDoc#596

Merged
kateinoigakukun merged 3 commits into
mainfrom
katei/7a24-bridgejs-ts2swif
Feb 6, 2026
Merged

BridgeJS: Generate Swift doc-comment based on JSDoc#596
kateinoigakukun merged 3 commits into
mainfrom
katei/7a24-bridgejs-ts2swif

Conversation

@kateinoigakukun

@kateinoigakukun kateinoigakukun commented Feb 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Added JSDoc parsing (description / @param / @returns) and DocC emission for callable / typed declarations in TS2Swift.

/**
 * A simple Document subset with WebIDL-derived comments.
 */
interface Document {
    /**
     * Creates an instance of the element for the specified tag.
     * @param tagName The name of an element.
     *
     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createElement)
     */
    createElement(tagName: string, options?: ElementCreationOptions): HTMLElement;
}
/// A simple Document subset with WebIDL-derived comments.
@JSClass struct Document {
    /// Creates an instance of the element for the specified tag.
    ///
    /// - Parameters:
    ///   - tagName: The name of an element.
    ///     
    ///     [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createElement)
    @JSFunction func createElement(_ tagName: String, _ options: JSUndefinedOr<ElementCreationOptions>) throws(JSException) -> Element
}

@kateinoigakukun
Doc comments from .d.ts JSDoc now flow into generated Swift DocC output. …
df68ef7 
- Added JSDoc parsing (description/@param/@returns) and DocC emission for callable/typed declarations, including classes/interfaces/enums, in `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/src/processor.js`, with guards to only read param/return tags on callable nodes.
- Added a documented fixture to cover the new behavior and updated the Vitest snapshot (`Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/fixtures/Documentation.d.ts`, `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/__snapshots__/ts2swift.test.js.snap`).

Tests:
- `npm test -- -u` (Plugins/BridgeJS/Sources/TS2Swift/JavaScript)

Next steps: optionally run `swift test --package-path ./Plugins/BridgeJS` to keep the Swift-side suite green.
@kateinoigakukun
Added richer WebIDL-derived doc coverage using the bridgejs-developme… …
b56d465 
…nt skill: new fixtures model lib.dom-style comments (MDN reference blocks, @param text) and updated Vitest snapshots to show how those JSDoc comments render into DocC. Key files: `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/fixtures/WebIDLDOMDocs.d.ts`, `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/fixtures/DOMLike.d.ts`, and the refreshed snapshot in `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/__snapshots__/ts2swift.test.js.snap`. Tests run: `npm test -- -u` (TS2Swift JavaScript).
@kateinoigakukun
Removed the DOM-like fixture and refreshed snapshots to drop its outp… …
3236fe9 
…ut. Changes: deleted `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/fixtures/DOMLike.d.ts` and updated `Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/__snapshots__/ts2swift.test.js.snap`.

Tests: `npm test -- -u` (TS2Swift JavaScript).
@kateinoigakukun kateinoigakukun changed the title Add WebIDL DOM doc fixtures for TS2Swift DocC output Feb 6, 2026
Copilot AI reviewed Feb 6, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

Pull request overview

This PR adds JSDoc parsing and Swift DocC comment generation to the TS2Swift processor in BridgeJS. The implementation parses JSDoc comments (description, @param, and @returns tags) from TypeScript declarations and emits corresponding Swift documentation comments with the /// prefix in DocC format.

Changes:

  • Added JSDoc parsing logic to extract descriptions, parameter documentation, and return value documentation from TypeScript declarations
  • Implemented Swift DocC format emission with proper formatting for parameters (- Parameters:) and returns (- Returns:) sections
  • Integrated documentation emission into all declaration types (functions, classes, interfaces, properties, methods, constructors, enums, and exported variables)

Reviewed changes

Copilot reviewed 2 out of 4 changed files in this pull request and generated 1 comment.

File Description
Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/fixtures/Documentation.d.ts New test fixture with basic JSDoc examples covering functions, interfaces, classes, and various parameter/return documentation patterns
Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/fixtures/WebIDLDOMDocs.d.ts New test fixture with WebIDL-style documentation (DOM API examples) including multi-line descriptions and MDN references
Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/__snapshots__/ts2swift.test.js.snap Updated snapshots showing generated Swift code with documentation comments for both new test fixtures
Plugins/BridgeJS/Sources/TS2Swift/JavaScript/src/processor.js Core implementation: added emitDocComment, renderJSDocText, splitDocumentationText, hasMeaningfulLine, and buildParameterNameMap methods; integrated documentation emission into all declaration rendering methods; removed old getFullJSDocText method and documentation field from visitPropertyDecl return type

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Hide details View details @kateinoigakukun kateinoigakukun merged commit bc752fc into main Feb 6, 2026
17 checks passed
@kateinoigakukun kateinoigakukun deleted the katei/7a24-bridgejs-ts2swif branch February 6, 2026 04:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@kateinoigakukun