-
-
Notifications
You must be signed in to change notification settings - Fork 63
BridgeJS: Generate Swift doc-comment based on JSDoc #596
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
- 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.
…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).
…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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
| for (const line of docLines) { | ||
| if (line.length === 0) { | ||
| this.swiftLines.push(prefix); | ||
| } else { | ||
| this.swiftLines.push(`${prefix} ${line}`); | ||
| } |
Copilot
AI
Feb 6, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The condition line.length === 0 doesn't handle lines that contain only whitespace. When blank lines from JSDoc are indented (e.g., at lines 585, 599), they become strings like " " which have length > 0, resulting in doc comments with trailing whitespace like /// instead of just ///.
Consider changing the condition to check for trimmed content: line.trim().length === 0. This will properly handle both empty lines and lines containing only whitespace.
Added JSDoc parsing (description /
@param/@returns) and DocC emission for callable / typed declarations in TS2Swift.