Js doc overloads by apendua · Pull Request #50789 · microsoft/TypeScript

Tomasz Lenarcik (apendua) · 2022-09-15T14:32:48Z

Since there was no final consensus, I ended up using a new @overload tag to ensure backwards compatibility, e.g.

/**
 * @overload
 * @param {number} x
 * @returns {'number'}
 */
/**
 * @overload
 * @param {string} x
 * @returns {'string'}
 */
/**
 * @overload
 * @param {boolean} x
 * @returns {'boolean'}
 */
/**
 * @param {unknown} x
 * @returns {string}
 */
function typeName(x) {
  return typeof x;
}

I would be happy to modify the implementation if someone suggests a better approach.

Deleted user (ghost) · 2022-09-15T14:33:00Z

All CLA requirements met.

Vale the Violet Mote (ValeTheVioletMote) · 2022-10-11T00:43:20Z

Looking forward to this!

Nathan Shively-Sanders (sandersn) · 2022-10-12T00:06:58Z


        function hasTrailingCommentsAtPosition(pos: number) {
            let result = false;
-            forEachTrailingCommentRange(currentSourceFile?.text || "", pos + 1, () => result = true);


why are these additional ends needed?

Nathan Shively-Sanders (@sandersn) I did this because I wanted to avoid JSDoc nodes duplication in .d.ts file, e.g.

// file.js /** * @overload * @param {string} value * @return {string} */ /** * @overload * @param {number} value * @return {number} */ /** * @overload * @param {unknown} value */ function myFunction(value) {}

would result in:

// file.d.ts /** * @overload * @param {string} value */ declare function myFunction(value: string): string; /** * @overload * @param {number} value */ declare function myFunction(value: number): number; /** * @overload * @param {string} value */ /** * @overload * @param {number} value */ /** * @overload * @param {unknown} value */ declare function myFunction(value);

Being able to specify end allowed me to limit the JSDocs that are emitted for a given parent node.

However this seems to only be one of many weird consequences of synthesizing declarations, which as you suggested does not seem to be the proper approach anyway.

Nathan Shively-Sanders (sandersn) · 2022-10-12T00:08:17Z

     *      return value of the callback.
     */
-    function iterateCommentRanges<T, U>(reduce: boolean, text: string, pos: number, trailing: boolean, cb: (pos: number, end: number, kind: CommentKind, hasTrailingNewLine: boolean, state: T, memo: U | undefined) => U, state: T, initial?: U): U | undefined {
+     function iterateCommentRanges<T, U>(reduce: boolean, text: string, pos: number, end: number | undefined, trailing: boolean, cb: (pos: number, end: number, kind: CommentKind, hasTrailingNewLine: boolean, state: T, memo: U | undefined) => U, state: T, initial?: U): U | undefined {


same question about end in the file

extra space typo:

Suggested change

function iterateCommentRanges<T, U>(reduce: boolean, text: string, pos: number, end: number | undefined, trailing: boolean, cb: (pos: number, end: number, kind: CommentKind, hasTrailingNewLine: boolean, state: T, memo: U | undefined) => U, state: T, initial?: U): U | undefined {

function iterateCommentRanges<T, U>(reduce: boolean, text: string, pos: number, end: number | undefined, trailing: boolean, cb: (pos: number, end: number, kind: CommentKind, hasTrailingNewLine: boolean, state: T, memo: U | undefined) => U, state: T, initial?: U): U | undefined {

Nathan Shively-Sanders (sandersn) · 2022-10-12T00:08:36Z


    export function copyLeadingComments(sourceNode: Node, targetNode: Node, sourceFile: SourceFile, commentKind?: CommentKind, hasTrailingNewLine?: boolean) {
-        forEachLeadingCommentRange(sourceFile.text, sourceNode.pos, getAddCommentsFunction(targetNode, sourceFile, commentKind, hasTrailingNewLine, addSyntheticLeadingComment));
+        forEachLeadingCommentRange(sourceFile.text, sourceNode.pos, /*end*/ undefined, getAddCommentsFunction(targetNode, sourceFile, commentKind, hasTrailingNewLine, addSyntheticLeadingComment));


same question about end here

Nathan Shively-Sanders (sandersn) · 2022-10-12T00:08:58Z


 declare namespace ts {
-    const versionMajorMinor = "4.9";
+    const versionMajorMinor = "4.8";


need to merge from main at some point

Nathan Shively-Sanders (sandersn) · 2022-10-12T00:10:28Z

@@ -0,0 +1,50 @@
+// @allowJs: true
+// @noEmit: true
+// @filename: 0.js


Suggested change

// @filename: 0.js

// @filename: jsFileMethodsOverloads.js

Nathan Shively-Sanders (sandersn) · 2022-10-12T00:10:42Z

@@ -0,0 +1,61 @@
+// @allowJs: true
+// @noEmit: true
+// @filename: 0.js


Suggested change

// @filename: 0.js

// @filename: jsFileFunctionOverloads.js

Nathan Shively-Sanders (sandersn) · 2022-10-13T20:46:18Z

@@ -0,0 +1,50 @@
+// @allowJs: true
+// @noEmit: true


please use // @outDir: dist/ and // @declaration: true to make sure that js->d.ts conversion works too.

Nathan Shively-Sanders (@sandersn) I tried this but didn't see any changes in the baseline files. What outcome I should be observing?

Did you remove @noEmit: true? You should see a baseline named jsFileMethodsOverloads.js and its last section should be a .d.ts file.

Nathan Shively-Sanders (@sandersn) Yup, that was it. Seems like it's working fine now. Thank you!

Nathan Shively-Sanders (sandersn) · 2022-10-13T20:52:01Z

+                const newParameters: ParameterDeclaration[] = [];
+                for (const tag of jsDoc.tags) {
+                    if (isJSDocParameterTag(tag) && tag.name.kind === SyntaxKind.Identifier) {
+                        const newParameter = factory.createParameterDeclaration(


Synthesising declarations is not a technique that works in the typescript compiler. A better approach would be to make sure all the jsdoc nodes are still available to the checker. In the checker, make sure that each @overload results in a signature. You'll want to start near getSignatureFromDeclaration, or its callers, I think.

Nathan Shively-Sanders (@sandersn) Agreed. I've also observed other BUGs related to IDE integrations that are coming from the fact that I am trying to synthesize those declarations, e.g. "did not expect identifier in trivia".

You'll want to start near getSignatureFromDeclaration, or its callers, I think.

Thank you for this suggestion! I've already tried that and it seems to be working much better:

https://github.com/microsoft/TypeScript/compare/main...apendua:js-doc-overload-tag?expand=1

How we should go about that? Should I close this pull request and open a new one?

It is up to you. I am fine with proceeding with this one; I squash merge PRs since it makes the git history easier to search.

Nathan Shively-Sanders (@sandersn) I ended up opening a new PR here: #51234

I also used this opportunity to rebase onto the latest main. Thank you again for all your suggestions!

Tomasz Lenarcik (apendua) · 2022-10-19T20:13:25Z

Closing this PR in favor of: #51234

Tomasz Lenarcik (apendua) added 4 commits September 15, 2022 15:19

Add support for JSDocOverloadTag

a51d682

Bind additional declarations from jsDoc

b578825

Update baseline for tests

e4b35c2

Add new tests along with baselines

9f26e98

TypeScript Bot (typescript-bot) added the For Backlog Bug PRs that fix a backlog bug label Sep 15, 2022

Nathan Shively-Sanders (sandersn) requested changes Oct 13, 2022

View reviewed changes

Nathan Shively-Sanders (sandersn) self-assigned this Oct 17, 2022

Nathan Shively-Sanders (sandersn) requested a review from navya9singh October 17, 2022 22:39

Tomasz Lenarcik (apendua) mentioned this pull request Oct 19, 2022

JSDoc overload tag #51234

Merged

Tomasz Lenarcik (apendua) closed this Oct 19, 2022

Microsoft (microsoft) locked as resolved and limited conversation to collaborators Oct 22, 2025

	function iterateCommentRanges<T, U>(reduce: boolean, text: string, pos: number, end: number \| undefined, trailing: boolean, cb: (pos: number, end: number, kind: CommentKind, hasTrailingNewLine: boolean, state: T, memo: U \| undefined) => U, state: T, initial?: U): U \| undefined {
	function iterateCommentRanges<T, U>(reduce: boolean, text: string, pos: number, end: number \| undefined, trailing: boolean, cb: (pos: number, end: number, kind: CommentKind, hasTrailingNewLine: boolean, state: T, memo: U \| undefined) => U, state: T, initial?: U): U \| undefined {

Uh oh!

Conversation

Tomasz Lenarcik (apendua) commented Sep 15, 2022

Uh oh!

Deleted user (ghost) commented Sep 15, 2022 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Vale the Violet Mote (ValeTheVioletMote) commented Oct 11, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nathan Shively-Sanders (sandersn) Oct 18, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tomasz Lenarcik (apendua) commented Oct 19, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Deleted user (ghost) commented Sep 15, 2022 •

edited by ghost

Loading

Nathan Shively-Sanders (sandersn) Oct 18, 2022 •

edited

Loading