Title: API: parameter documentation (getDocumentationComment / getJsDocTags) diverges from the classic services in TypeScript 7.1 · Issue #64919 · microsoft/TypeScript · GitHub
Open Graph Title: API: parameter documentation (getDocumentationComment / getJsDocTags) diverges from the classic services in TypeScript 7.1 · Issue #64919 · microsoft/TypeScript
X Title: API: parameter documentation (getDocumentationComment / getJsDocTags) diverges from the classic services in TypeScript 7.1 · Issue #64919 · microsoft/TypeScript
Description: 🔎 Search Terms typescript 7.1 api getDocumentationComment getJsDocTags parameter jsdoc inherit override constructor parameter base property findBaseOfDeclaration typescript/sync 🕗 Version & Regression Information This is the behavior of ...
Open Graph Description: 🔎 Search Terms typescript 7.1 api getDocumentationComment getJsDocTags parameter jsdoc inherit override constructor parameter base property findBaseOfDeclaration typescript/sync 🕗 Version & Regress...
X Description: 🔎 Search Terms typescript 7.1 api getDocumentationComment getJsDocTags parameter jsdoc inherit override constructor parameter base property findBaseOfDeclaration typescript/sync 🕗 Version & Reg...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/64919
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"API: parameter documentation (getDocumentationComment / getJsDocTags) diverges from the classic services in TypeScript 7.1","articleBody":"### 🔎 Search Terms\n\ntypescript 7.1 api getDocumentationComment getJsDocTags parameter jsdoc inherit override constructor parameter base property findBaseOfDeclaration typescript/sync\n\n### 🕗 Version & Regression Information\n\n- This is the behavior of the programmatic API shipped in `typescript@7.1.0-beta` (`typescript/sync` and `typescript/async`); I also reproduced it on the final typescript-go staging commit before that repository closed.\n- The classic compiler behaves as expected on every version I checked (5.9.x and 6.0.x), so this is a divergence of the native implementation from the long-standing services semantics rather than a regression within a release line.\n\n### ⏯ Playground Link\n\nNot applicable: the behavior is only observable through the programmatic API, not through type checking or emit. A self-contained reproduction (one TypeScript file plus two small Node scripts that print the same report from the classic API and from `typescript/sync`) is included below and needs only `npm i typescript@6 typescript7@npm:typescript@7.1.0-beta`.\n\n### 💻 Code\n\n```ts\nexport abstract class MatcherBase {\n /**\n * Tests the value.\n * @param actual the target to match\n */\n public abstract test(actual: string): void;\n}\n\n/** Overrides test with NO JSDoc at all. */\nexport class PlainCapture extends MatcherBase {\n public test(actual: string): void { void actual; }\n}\n\n/** Base class with a documented property. */\nexport class WithCount {\n /** How many widgets there are. */\n public readonly count: number = 0;\n}\n\n/** Subclass constructor without JSDoc. */\nexport class Counted extends WithCount {\n constructor(count: number) { super(); void count; }\n}\n\nexport class Tagged {\n /**\n * Creates a tag.\n * @param key The string key for the tag.\n */\n constructor(key: string) { void key; }\n}\n```\n\nFor every parameter symbol (from `checker.getSignatureFromDeclaration(decl).getParameters()`), I compare `symbol.getDocumentationComment(checker)` and `symbol.getJsDocTags(checker)` between the classic API (`ts.createProgram`, `ts.displayPartsToString`) and the 7.1 API (`new API({ cwd }).createSnapshot({ openProjects: [tsconfig] })`, `snapshot.getConfiguredProject(tsconfig).checker`).\n\n```sh\nnpm i typescript@6 typescript7@npm:typescript@7.1.0-beta\nnode tsgo-jsdoc-param-run-classic.mjs ./tsgo-jsdoc-param-repro.ts > classic.txt\nnode tsgo-jsdoc-param-run-ts71.mjs . > ts71.txt # a tsconfig.json in . must include tsgo-jsdoc-param-repro.ts\ndiff classic.txt ts71.txt\n```\n\n### 🙁 Actual behavior\n\n| Symbol | 7.1 API returns |\n|---|---|\n| `PlainCapture.test` parameter `actual`, documentation comment | `\"the target to match\"` — inherited from `MatcherBase.test` even though the override has no JSDoc |\n| `Counted` constructor parameter `count`, documentation comment | `\"\"` |\n| `Tagged` constructor parameter `key`, tags | `[]` |\n| `MatcherBase.test` parameter `actual`, tags | `[]` |\n\nIn other words: method parameters inherit `@param` text from base signatures, constructor parameters do not fall back to a same-named base property, and `getJsDocTags` is always empty for parameter symbols.\n\n\n### 🙂 Expected behavior\n\n| Symbol | classic API returns |\n|---|---|\n| `PlainCapture.test` parameter `actual`, documentation comment | `\"\"` — `getJSDocParameterTags` only consults the hosting declaration's own JSDoc, so overrides never inherit parameter docs |\n| `Counted` constructor parameter `count`, documentation comment | `\"How many widgets there are.\"` — `findBaseOfDeclaration` resolves a constructor parameter against the class's super types and takes the documentation of the same-named property |\n| `Tagged` constructor parameter `key`, tags | `[{ name: \"param\", text: \"key The string key for the tag.\" }]` |\n| `MatcherBase.test` parameter `actual`, tags | `[{ name: \"param\", text: \"actual the target to match\" }]` |\n\nThe relevant classic code is `getDocumentationComment` / `findBaseOfDeclaration` in `src/services/utilities.ts` (for a declaration whose parent is a constructor, the base search runs over the class's heritage clauses and looks up a property named like the parameter; for a method parameter the \"class or interface declaration\" resolves to the method itself, which has no super types, hence no inheritance) and `getJSDocParameterTags` in `src/compiler/utilities.ts`.\n\n### Additional information about the issue\n\nI ran into this while experimenting with running jsii (the AWS CDK's multi-language binding generator) on the TypeScript 7 programmatic API. jsii derives the parameter documentation in its `.jsii` assemblies from these two methods, and the divergence produced hundreds of member-level differences against the classic output on `aws-cdk-lib`, in both directions (documentation appearing on overridden methods that should have none, and constructor parameter documentation missing). I currently work around it by reading `@param` text from the source text instead of the documentation APIs.\n\nI have a fix ready on a fork branch (`fix/jsdoc-param-resolution` on WinterYukky/TypeScript, based on the `v7.1-beta` tag) that restricts parameter `@param` lookup to the hosting declaration's own JSDoc (with the overload first-signature hop), adds the `findBaseOfDeclaration` fallback for constructor parameters, and makes `getJsDocTags` return parameter tags. With it the reproduction above prints byte-identical reports from the classic API and from `typescript/sync`, the Go test suites for `internal/ls` and `internal/api` pass, and the full `packages/typescript` API test suite passes unchanged. I am happy to open it as a PR once this issue is triaged.\n","author":{"url":"https://github.com/WinterYukky","@type":"Person","name":"WinterYukky"},"datePublished":"2026-10-22T07:15:19Z","url":"https://github.com/microsoft/TypeScript/issues/64919"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:78087cb0-a902-29c3-5fd8-3b0f072333ce |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | AF8A:14F601:DAA55E:118D931:6B00F242 |
| html-safe-nonce | e28f7302f538e054133f5b9deee48788112186409ca30808d13c2518259ddd9c |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBRjhBOjE0RjYwMTpEQUE1NUU6MTE4RDkzMTo2QjAwRjI0MiIsInZpc2l0b3JfaWQiOiI3NDc1NDY4NDk1NDg0OTQwODY2IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 8ec5db7228b09cc0fa7200adec2c26abc6890c7e49de4675df21af5d85c3d941 |
| hovercard-subject-tag | issue:5974843262 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/microsoft/TypeScript/64919/issue_layout |
| twitter:image | https://opengraph.githubassets.com/18a2880b0b9d4f8df989d7b35b74f6d4ed7a99703d89ec1f8755780bf7299ab6/microsoft/TypeScript/issues/64919 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/18a2880b0b9d4f8df989d7b35b74f6d4ed7a99703d89ec1f8755780bf7299ab6/microsoft/TypeScript/issues/64919 |
| og:image:alt | 🔎 Search Terms typescript 7.1 api getDocumentationComment getJsDocTags parameter jsdoc inherit override constructor parameter base property findBaseOfDeclaration typescript/sync 🕗 Version & Regress... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | WinterYukky |
| hostname | github.com |
| expected-hostname | github.com |
| None | 4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc |
| turbo-cache-control | no-preview |
| go-import | github.com/microsoft/TypeScript git https://github.com/microsoft/TypeScript.git |
| octolytics-dimension-user_id | 6154722 |
| octolytics-dimension-user_login | microsoft |
| octolytics-dimension-repository_id | 20929025 |
| octolytics-dimension-repository_nwo | microsoft/TypeScript |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 20929025 |
| octolytics-dimension-repository_network_root_nwo | microsoft/TypeScript |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 9983dd5da06943f833c971dd5b6bc988e2858be5 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width