Title: intellisense for JSDocs on function overloads without needing to duplicate the JSDoc · Issue #51005 · microsoft/TypeScript · GitHub
Open Graph Title: intellisense for JSDocs on function overloads without needing to duplicate the JSDoc · Issue #51005 · microsoft/TypeScript
X Title: intellisense for JSDocs on function overloads without needing to duplicate the JSDoc · Issue #51005 · microsoft/TypeScript
Description: Suggestion 🔍 Search Terms intellisense for JSDocs on function overloads without needing to duplicate the JSDoc auto complete JSDocs function overloads ✅ Viability Checklist My suggestion meets these guidelines: This wouldn't be a breakin...
Open Graph Description: Suggestion 🔍 Search Terms intellisense for JSDocs on function overloads without needing to duplicate the JSDoc auto complete JSDocs function overloads ✅ Viability Checklist My suggestion meets thes...
X Description: Suggestion 🔍 Search Terms intellisense for JSDocs on function overloads without needing to duplicate the JSDoc auto complete JSDocs function overloads ✅ Viability Checklist My suggestion meets thes...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/51005
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"intellisense for JSDocs on function overloads without needing to duplicate the JSDoc","articleBody":"# Suggestion\r\n\r\n## 🔍 Search Terms\r\n\r\n- intellisense for JSDocs on function overloads without needing to duplicate the JSDoc\r\n- auto complete\r\n- JSDocs\r\n- function overloads\r\n\r\n## ✅ Viability Checklist\r\n\r\n\u003c!--\r\n Suggestions that don't meet all these criteria are very, very unlikely to be accepted.\r\n We always recommend reviewing the TypeScript design goals before investing time writing\r\n a proposal for ideas outside the scope of the project.\r\n-->\r\nMy suggestion meets these guidelines:\r\n\r\n* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code\r\n* [x] This wouldn't change the runtime behavior of existing JavaScript code\r\n* [x] This could be implemented without emitting different JS based on the types of the expressions\r\n* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)\r\n* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).\r\n\r\n## ⭐ Suggestion\r\n\r\nWhen you have a really long JSDoc that describes a function (say 10+ lines) and you need 3~4 function overloads for that function. The only way to properly have the JSDocs show up on all overload cases when you actually import and use the function is to duplicate the JSDocs for each single function overload...\r\n\r\nFR: We need VSCode intellisense for our JSDocs to **show up on ALL function overloads** _without_ needing to duplicate the JSDocs on every overload.\r\n\r\n## 📃 Motivating Example\r\n\r\nHere is a very common example I use countless of times throughout my code where an object that's potentially `undefined` is parsed in a function, but when we know the payload is not undefined we want to make sure the return type is also not.\r\n\r\n```ts\r\ntype Person = { firstName: string; lastName: string }\r\ntype PersonParsed = { fullName: string }\r\n\r\nexport function parsePerson(person: Person): PersonParsed\r\nexport function parsePerson(person: undefined): undefined\r\nexport function parsePerson(person: Person | undefined): PersonParsed | undefined\r\nexport function parsePerson(person?: Person): PersonParsed | undefined {\r\n // ... implementation\r\n}\r\n```\r\n\r\nA perfect use-case for function overloads! But then comes your detailed JSDoc and it will look like this:\r\n\r\n```ts\r\ntype Person = { firstName: string; lastName: string }\r\ntype PersonParsed = { fullName: string }\r\n\r\n/**\r\n * Here is a very long JSDoc\r\n *\r\n * Maybe it describes what the function can do / when it should be used\r\n * - Maybe it has\r\n * - some bullet lists\r\n *\r\n * @see https://some-related-documentation...\r\n * @example\r\n * ```js\r\n * // some usage examples:\r\n * const { fullname } = parsePerson(person) || {}\r\n * console.log(`fullname → `, fullname)\r\n * ```\r\n */\r\nexport function parsePerson(person: Person): PersonParsed\r\n/**\r\n * Here is a very long JSDoc\r\n *\r\n * Maybe it describes what the function can do / when it should be used\r\n * - Maybe it has\r\n * - some bullet lists\r\n *\r\n * @see https://some-related-documentation...\r\n * @example\r\n * ```js\r\n * // some usage examples:\r\n * const { fullname } = parsePerson(person) || {}\r\n * console.log(`fullname → `, fullname)\r\n * ```\r\n */\r\nexport function parsePerson(person: undefined): undefined\r\n/**\r\n * Here is a very long JSDoc\r\n *\r\n * Maybe it describes what the function can do / when it should be used\r\n * - Maybe it has\r\n * - some bullet lists\r\n *\r\n * @see https://some-related-documentation...\r\n * @example\r\n * ```js\r\n * // some usage examples:\r\n * const { fullname } = parsePerson(person) || {}\r\n * console.log(`fullname → `, fullname)\r\n * ```\r\n */\r\nexport function parsePerson(person: Person | undefined): PersonParsed | undefined\r\n/**\r\n * Here is a very long JSDoc\r\n *\r\n * Maybe it describes what the function can do / when it should be used\r\n * - Maybe it has\r\n * - some bullet lists\r\n *\r\n * @see https://some-related-documentation...\r\n * @example\r\n * ```js\r\n * // some usage examples:\r\n * const { fullname } = parsePerson(person) || {}\r\n * console.log(`fullname → `, fullname)\r\n * ```\r\n */\r\nexport function parsePerson(person?: Person): PersonParsed | undefined {\r\n // ... implementation\r\n}\r\n```\r\n\r\n## 💻 Use Cases\r\n\r\nUse case explained in the previous section.\r\n\r\n### Conclusion\r\n\r\nWe need VSCode intellisense for our JSDocs to **show up on ALL function overloads** _without_ needing to duplicate the JSDocs on every overload.\r\n\r\n","author":{"url":"https://github.com/mesqueeb","@type":"Person","name":"mesqueeb"},"datePublished":"2022-09-30T04:03:41Z","url":"https://github.com/microsoft/TypeScript/issues/51005"}
| 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:81b02d31-243a-7693-3832-f9de21a770d3 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | E7AC:117C62:2555024:31D3B8F:6B01A456 |
| html-safe-nonce | 12d3a5a12795fd8dbce15d625dadfb6f5a2aab87548272073c7ab999264bde5b |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFN0FDOjExN0M2MjoyNTU1MDI0OjMxRDNCOEY6NkIwMUE0NTYiLCJ2aXNpdG9yX2lkIjoiMjExODkzNTY3MjE5MzY1NTg5NCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | f25b917eb3174741df39a6b05fedad207297283daa5a86bad991d427227779d3 |
| hovercard-subject-tag | issue:1391789702 |
| 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/51005/issue_layout |
| twitter:image | https://opengraph.githubassets.com/78d56029b0353e0f59c3b093c7e7bd1d12d15811d40c41b3456acce6931798d3/microsoft/TypeScript/issues/51005 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/78d56029b0353e0f59c3b093c7e7bd1d12d15811d40c41b3456acce6931798d3/microsoft/TypeScript/issues/51005 |
| og:image:alt | Suggestion 🔍 Search Terms intellisense for JSDocs on function overloads without needing to duplicate the JSDoc auto complete JSDocs function overloads ✅ Viability Checklist My suggestion meets thes... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | mesqueeb |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| 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 | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width