René's URL Explorer Experiment


Title: Discussion: Support @typedef Tag in JsDoc Comments [Salsa] · Issue #7758 · microsoft/TypeScript · GitHub

Open Graph Title: Discussion: Support @typedef Tag in JsDoc Comments [Salsa] · Issue #7758 · microsoft/TypeScript

X Title: Discussion: Support @typedef Tag in JsDoc Comments [Salsa] · Issue #7758 · microsoft/TypeScript

Description: Currently type annotation is only allowed in TypeScript file. Although we do allow .d.ts files to be consumed by JavaScript files, there are already code bases employing JsDoc @typedef tag to define types within JavaScript files (Google ...

Open Graph Description: Currently type annotation is only allowed in TypeScript file. Although we do allow .d.ts files to be consumed by JavaScript files, there are already code bases employing JsDoc @typedef tag to defin...

X Description: Currently type annotation is only allowed in TypeScript file. Although we do allow .d.ts files to be consumed by JavaScript files, there are already code bases employing JsDoc @typedef tag to defin...

Opengraph URL: https://github.com/microsoft/TypeScript/issues/7758

X: @github

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Discussion: Support @typedef Tag in JsDoc Comments [Salsa]","articleBody":"Currently type annotation is only allowed in TypeScript file. Although we do allow `.d.ts` files to be consumed by JavaScript files, there are already code bases employing JsDoc `@typedef` tag to define types within JavaScript files (Google Closure, etc). Supporting `@typedef` tag will enhance the editing experience for Salsa on these existing code bases.\n\nThe purpose of `@typedef` is to define a new type that can be used in other JsDoc comment annotations, similar to interface or type alias declaration in TypeScript. However, because there is no definite standard on the shape of `@typedef`, its has several popular dialects. The most common cases I found are as follows:\n\nCase 1:\n\n``` js\n/**\n * @typedef {(string | number)} NumberLike\n */\n```\n\nCase 2:\n\n``` js\n/**\n * @typedef {Object} People\n * @property {number} id the unique id\n * @property {string} name - your name\n */\n```\n\nCase 3:\n\n``` js\n/**\n * @typedef People\n * @type {Object}\n * @property {number} id the unique id\n * @property {string} name - your name\n */\n```\n\nCase 4:\n\n``` js\n/** @typedef {(string | number)} */\nvar NumberLike;\n```\n\nCase 5:\n\n``` js\n/** @typedef {(string | number)} */\nNumberLike;\n```\n\nCase 6:\n\n``` js\n/** @typedef {{ count: number }} */\nPeople;\n\n/**\n * @typedef {{\n *     id: number,\n *     name: string\n * }}\n */\nPeople.person;\n\n/**@type {People.person}*/\nvar p;\n```\n\nThere are several difficulties / design choices for the current TypeScript type system to understand the above cases:\n1. Does the code need to be valid JavaScript code if ignoring the comments?\n   For example:\n   \n   ``` js\n     /**@typedef {string}*/\n     StringType;\n   ```\n   \n   is totally fine with the Google Closure compiler, while running the code directly will generate errors because the variable `StringType` is not defined. \n2. How does these types translate to TypeScript types?\n   In simple cases, the `@typedef` functions similarly to type alias in TypeScript. However, the type name defined by `@typedef` can be a dotted name (as shown in case 6), while in TypeScript type alias name has to be an identifier. And like in case 6, a defined type (`People`) may be augmented later (added `People.person` property), which is hard to do for a type alias.\n   \n   The other route is to represent all the types as interfaces. This solves some of the the augmentation issue, because interfaces can have multiple declarations and be merged together, however it has flaws too. For example:\n   \n   ``` js\n     /**@typedef {(string | number)} Id*/\n     /**@typedef {string} Id.name*/\n   ```\n   \n   in which the union type is hard to represent using interfaces.\n3. For case 4 or case 5, do we create both a value declaration and a type declaration for the variable? Imagine the following code:\n   \n   ``` js\n   /**@typedef {(string | number)} */\n   var foo;\n   ...\n   var foo = 10; // \u003c- What is \"foo\" after this line? Should we give you an error / warning?\n   if (foo) { // If I call \"Go to declaration\" on \"foo\", where will I go to?\n       ...\n   }\n   ```\n   \n   In addition, if the variable only has a type declaration, potentially naming conflicts could happen. For exapmle, the following TypeScript code wouldn't have any error:\n   \n   ``` ts\n   type Test = string;\n   function Test() { return 10; };\n   var result = Test();\n   ```\n   \n   However, we are reporting syntax errors for the corresponding JavaScript code using `@typedef`:\n   \n   ``` js\n   /**@typedef {string}*/\n   var Test;\n   function Test() { return 10; };\n   var result = Test();\n   ```\n4. Types defined by `@typedef` should have a scope, and it may or may not be related to their parent node (they may not even have a parent node). For example:\n   \n   ``` ts\n   function A () {\n       /**@typedef {string} TypeA*/\n   \n       /**@typedef {string} TypeB*/\n       /**@param {string} p1*/\n       function B () {\n           ...\n       }\n   }\n   ```\n   \n   Both `TypeA` and `TypeB` should live inside the block scope that function `A` contains.\n\nFeedback is welcome to these questions, as I am not a heavy JsDoc user, so I might have missed some scenarios. I will keep prototyping potential solutions and update with a proposal once a reasonable design was reached.\n","author":{"url":"https://github.com/zhengbli","@type":"Person","name":"zhengbli"},"datePublished":"2016-04-01T01:42:10Z","url":"https://github.com/microsoft/TypeScript/issues/7758"}

react-profiling0
react-import-mapreact,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-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:77ebc231-36cc-933e-98fb-a7eca458a104
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idDC72:3D8CBB:D1B213:1160642:6B00F80B
html-safe-nonce17cb0eba77301c3732b9b28e736f93042ced0167d89f1d2363bd1a51e715f1be
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEQzcyOjNEOENCQjpEMUIyMTM6MTE2MDY0Mjo2QjAwRjgwQiIsInZpc2l0b3JfaWQiOiI2NjUzMzgzNjc0NTM0MzYxMTAwIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0=
visitor-hmac98f40f636565f96dd7af826df70bc0e43749c17a53a40dccffb93eb865d71789
hovercard-subject-tagissue:145061625
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/microsoft/TypeScript/7758/issue_layout
twitter:imagehttps://opengraph.githubassets.com/316f5ed38e42940419daca285c479960b7fbab367286230812a43620e28800aa/microsoft/TypeScript/issues/7758
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/316f5ed38e42940419daca285c479960b7fbab367286230812a43620e28800aa/microsoft/TypeScript/issues/7758
og:image:altCurrently type annotation is only allowed in TypeScript file. Although we do allow .d.ts files to be consumed by JavaScript files, there are already code bases employing JsDoc @typedef tag to defin...
og:image:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamezhengbli
hostnamegithub.com
expected-hostnamegithub.com
Nonee208d86428ec00a57ade75058166297440e8128a01e5287c31a53dc042bbf187
turbo-cache-controlno-preview
go-importgithub.com/microsoft/TypeScript git https://github.com/microsoft/TypeScript.git
octolytics-dimension-user_id6154722
octolytics-dimension-user_loginmicrosoft
octolytics-dimension-repository_id20929025
octolytics-dimension-repository_nwomicrosoft/TypeScript
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id20929025
octolytics-dimension-repository_network_root_nwomicrosoft/TypeScript
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release7dafd017fb7809a839c443dba08622af38e63c09
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/microsoft/TypeScript/issues/7758#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmicrosoft%2FTypeScript%2Fissues%2F7758
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmicrosoft%2FTypeScript%2Fissues%2F7758
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=microsoft%2FTypeScript
Reloadhttps://github.com/microsoft/TypeScript/issues/7758
Reloadhttps://github.com/microsoft/TypeScript/issues/7758
Reloadhttps://github.com/microsoft/TypeScript/issues/7758
microsofthttps://github.com/microsoft
TypeScripthttps://github.com/microsoft/TypeScript
Codehttps://github.com/microsoft/TypeScript
Issues5k (5k)https://github.com/microsoft/TypeScript/issues
Pull requests309 (309)https://github.com/microsoft/TypeScript/pulls
Actionshttps://github.com/microsoft/TypeScript/actions
Projectshttps://github.com/microsoft/TypeScript/projects
Wikihttps://github.com/microsoft/TypeScript/wiki
Security and qualityhttps://github.com/microsoft/TypeScript/security
Insightshttps://github.com/microsoft/TypeScript/insights
https://github.com/microsoft/TypeScript
New issuehttps://github.com/login?return_to=https://github.com/microsoft/TypeScript/issues/7758
New issuehttps://github.com/login?return_to=https://github.com/microsoft/TypeScript/issues/7758
Discussion: Support @typedef Tag in JsDoc Comments [Salsa]https://github.com/microsoft/TypeScript/issues/7758#top
https://github.com/zhengbli
FixedA PR has been merged for this issuehttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Fixed%22
SuggestionAn idea for TypeScripthttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Suggestion%22
TypeScript 2.0https://github.com/microsoft/TypeScript/milestone/1
https://github.com/zhengbli
Zhengbo Li (zhengbli)https://github.com/zhengbli
on Apr 1, 2016https://github.com/microsoft/TypeScript/issues/7758#issue-145061625
Zhengbo Li (zhengbli)https://github.com/zhengbli
DiscussionIssues which may not have code impacthttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Discussion%22
Salsahttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Salsa%22
on Apr 1, 2016https://github.com/microsoft/TypeScript/issues/7758#event-610665449
https://github.com/DanielRosenwasser
Daniel Rosenwasser (DanielRosenwasser)https://github.com/DanielRosenwasser
on Apr 1, 2016https://github.com/microsoft/TypeScript/issues/7758#issuecomment-204298329
https://github.com/mhegazy
Mohamed Hegazy (mhegazy)https://github.com/mhegazy
on Apr 1, 2016https://github.com/microsoft/TypeScript/issues/7758#issuecomment-204532323
https://github.com/zhengbli
Zhengbo Li (zhengbli)https://github.com/zhengbli
on Apr 1, 2016https://github.com/microsoft/TypeScript/issues/7758#issuecomment-204562371
Daniel Rosenwasser (@DanielRosenwasser)https://github.com/DanielRosenwasser
Mohamed Hegazy (@mhegazy)https://github.com/mhegazy
Zhengbo Li (zhengbli)https://github.com/zhengbli
completedhttps://github.com/microsoft/TypeScript/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Acompleted
on Jun 17, 2016https://github.com/microsoft/TypeScript/issues/7758#event-695557324
Mohamed Hegazy (mhegazy)https://github.com/mhegazy
SuggestionAn idea for TypeScripthttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Suggestion%22
FixedA PR has been merged for this issuehttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Fixed%22
DiscussionIssues which may not have code impacthttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Discussion%22
on Jun 17, 2016https://github.com/microsoft/TypeScript/issues/7758#event-695652443
Mohamed Hegazy (mhegazy)https://github.com/mhegazy
TypeScript 2.0https://github.com/microsoft/TypeScript/milestone/1
on Jun 17, 2016https://github.com/microsoft/TypeScript/issues/7758#event-695652509
Mohamed Hegazy (mhegazy)https://github.com/mhegazy
Zhengbo Li (zhengbli)https://github.com/zhengbli
on Jun 17, 2016https://github.com/microsoft/TypeScript/issues/7758#event-695652681
microsofthttps://github.com/microsoft
on Jun 19, 2018https://github.com/microsoft/TypeScript/issues/7758#event-1689645811
Sign up for freehttps://github.com/signup?return_to=https://github.com/microsoft/TypeScript/issues/7758
Sign in to commenthttps://github.com/login?return_to=https://github.com/microsoft/TypeScript/issues/7758
Zhengbo Li (zhengbli)https://github.com/zhengbli
FixedA PR has been merged for this issuehttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Fixed%22
SuggestionAn idea for TypeScripthttps://github.com/microsoft/TypeScript/issues?q=state%3Aopen%20label%3A%22Suggestion%22
TypeScript 2.0https://github.com/microsoft/TypeScript/milestone/1
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.