Skip to content

fix(parser): handle multiple JSDoc blocks gracefully#2611

Open
SSDWGG wants to merge 1 commit into
airtasker:masterfrom
SSDWGG:fix/handle-multiple-jsdoc
Open

fix(parser): handle multiple JSDoc blocks gracefully#2611
SSDWGG wants to merge 1 commit into
airtasker:masterfrom
SSDWGG:fix/handle-multiple-jsdoc

Conversation

@SSDWGG
Copy link
Copy Markdown

@SSDWGG SSDWGG commented May 15, 2026

Summary

Fixes #1080 — when multiple JSDoc blocks precede a single TypeScript declaration (e.g. a copyright header /** ... */ followed by a documentation block /** ... */), getJsDoc() now catches the error from ts-morph and returns undefined gracefully instead of aborting generation entirely.

Reproducer

/**
 * Some General Documentation
 */

/**
 * Some Interface Documentation
 */
interface CreateUserRequest {
  firstName: String;
}

Running spot generate previously threw: Error: expected at most 1 jsDoc node, got 2

Change

Wrapped node.getJsDocs() in a try-catch within getJsDoc(). When ts-morph rejects a node with multiple JSDoc blocks, the function returns undefined (no description) rather than crashing the generation.

Why this is safe

  • When getJsDoc() returns undefined, callers already handle it — they leave the description field empty
  • The alternative (aborting generation) is strictly worse
  • The comment on the original function said "the node is expected to have no more than one JSDoc" — this fix removes that expectation

Checklist

  • Minimal change (3-line try-catch)
  • No behavior change for single-JSDoc nodes
  • All existing callers handle undefined return

When a declaration is preceded by multiple JSDoc blocks (e.g. a
copyright header and a documentation block), ts-morph may throw
"expected at most 1 jsDoc node". Wrap getJsDocs() in a try-catch
to gracefully return undefined instead of aborting generation.

Fixes airtasker#1080
@SSDWGG SSDWGG requested a review from a team as a code owner May 15, 2026 10:03
@SSDWGG SSDWGG requested a review from thanhnamit May 15, 2026 10:03
@CLAassistant
Copy link
Copy Markdown

CLAassistant commented May 15, 2026

CLA assistant check
All committers have signed the CLA.

Copy link
Copy Markdown
Contributor

@timdawborn timdawborn left a comment

Choose a reason for hiding this comment

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

Looks good to me.

Can you please add a unit test for this behavioural change though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Handle Multiple JSDoc Correctly

3 participants