Visitar URL original
fix(tasks): use .jsdoc.json with build/esm/src for ESM doc generation by feywind · Pull Request #9522 · googleapis/google-cloud-node · GitHub
Skip to content

fix(tasks): use .jsdoc.json with build/esm/src for ESM doc generation - #9522

Open
feywind wants to merge 1 commit into
googleapis:mainfrom
feywind:fix/tasks-jsdoc-esm
Open

feywind wants to merge 1 commit into
googleapis:mainfrom
feywind:fix/tasks-jsdoc-esm

Conversation

@feywind

@feywind feywind commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes the failing npm run docs / pnpm run docs JSDoc generation for @google-cloud/tasks (currently the only generated GAPIC package in packages/ with "type": "module" / esm: true):

  1. package.json "docs" script: packages/google-cloud-tasks/package.json previously referenced .jsdoc.js ("docs": "jsdoc -c .jsdoc.js"), which no longer existed after the ESM migration (package.json is listed in default.keep in librarian.yaml).
  2. JSDoc config format (.jsdoc.json): jsdoc (cli.js) only uses require() when path.extname(confPath) === '.js'; for all other extensions (.cjs, .json, etc.), it reads the file as text and runs JSON.parse(stripJsonComments(...)). As a result, .jsdoc.cjs with module.exports = { ... } fails with SyntaxError: Unexpected token 'm' ... is not valid JSON, while .jsdoc.js inside a "type": "module" package returns an empty module namespace from require(). Switching to .jsdoc.json (matching handwritten/storage/.jsdoc.json) resolves this cleanly.
  3. source.include path: Dual ESM/CJS packages compile .js sources to build/esm/src (rather than build/src). Updated source.include to ["build/esm/src", "protos"] so JSDoc locates the compiled ESM sources.

A companion PR updates the ESM template and baselines in core/generator/gapic-generator-typescript so future generations emit .jsdoc.json directly.

Verification

  • Ran pnpm run compile and pnpm run docs in packages/google-cloud-tasks and verified ./docs is generated cleanly with exit code 0.

@feywind
feywind requested a review from a team as a code owner October 5, 2026 21:18
@product-auto-label product-auto-label Bot added the api: cloudtasks Issues related to the Cloud Tasks API. label Oct 5, 2026

@gemini-code-assist gemini-code-assist Bot 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.

Code Review

This pull request replaces the JavaScript-based JSDoc configuration file with a JSON-based configuration file (.jsdoc.json) in the packages/google-cloud-tasks directory, updating the source path from build/src to build/esm/src. Additionally, the docs script in package.json is updated to reference the new JSON configuration file. I have no feedback to provide.

@feywind

feywind commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

Thanks. We'll need to wait for #9523 before merging this one.

@feywind feywind added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Oct 6, 2026

This branch has not been deployed

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

Labels

api: cloudtasks Issues related to the Cloud Tasks API. do not merge Indicates a pull request not ready for merge, due to either quality or timing.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants