expose jsdoc factory by Kingwl · Pull Request #29539 · microsoft/TypeScript

Wenlu Wang (Kingwl) · 2019-01-23T10:21:56Z

Klaus Meinhardt (ajafff)

Do you plan on adding the corresponding updateJSDocXXX functions?

Klaus Meinhardt (ajafff) · 2019-01-23T11:50:28Z

    }

+    export function createJSDocUnknownTag() {
+        return createSynthesizedNode(SyntaxKind.JSDocTag) as JSDocUnknownTag;


is this function even necessary? createJSDocTag should be used instead

JSDocUnknownTag haven't gov the tagName

it has, it extends JSDocTag and therefore contains tagName and comment

Klaus Meinhardt (ajafff) · 2019-01-23T11:50:58Z

-    /* @internal */
    function createJSDocTag<T extends JSDocTag>(kind: T["kind"], tagName: string): T {
        const node = createSynthesizedNode(kind) as T;
        node.tagName = createIdentifier(tagName);


this is missing an assignment to node.comment

That not my fault,
/cc: Daniel Rosenwasser (@DanielRosenwasser)

Klaus Meinhardt (ajafff) · 2019-01-23T11:52:28Z

+        return createSynthesizedNode(SyntaxKind.JSDocTag) as JSDocUnknownTag;
+    }
+
+    export function createJSDocAugmentsTag(tagName: string, classExpression: ExpressionWithTypeArguments & { expression: Identifier | PropertyAccessEntityNameExpression }, comment?: string) {


prefer classExpression: JSDocAugmentsTag['class']

Klaus Meinhardt (ajafff) · 2019-01-23T11:53:14Z

+    export function createJSDocEnumTag(tagName: string, typeExpression?: JSDocTypeExpression, comment?: string) {
+        const node = createJSDocTag<JSDocEnumTag>(SyntaxKind.JSDocEnumTag, tagName);
+        node.typeExpression = typeExpression;
+        node.comment = comment;


this assignment should be done in createJSDocTag

Klaus Meinhardt (ajafff) · 2019-01-24T08:51:30Z

+        return node;
+    }
+
+    export function createJSDocPropertyLikeTag<T extends JSDocPropertyLikeTag>(kind: T["kind"], tagName: Identifier, name: EntityName, isNameFirst: boolean, isBracketed: boolean, typeExpression?: JSDocTypeExpression, comment?: string) {


should this helper function really be exported?

Klaus Meinhardt (ajafff) · 2019-01-24T09:12:57Z

+        return createJSDocTagWithTypeExpression<JSDocThisTag>(SyntaxKind.JSDocThisTag, tagName, typeExpression, comment);
+    }
+
+    export function createJSDocTemplateTag(tagName: string, typeParameters: NodeArray<TypeParameterDeclaration>, constraint?: JSDocTypeExpression, comment?: string) {


consider using ReadonlyArray over NodeArray for easier to use API. in the function body you can then use toNodeArray or asNodeArray to convert it as necessary

Klaus Meinhardt (ajafff) · 2019-01-24T11:06:58Z


-    /* @internal */
-    function createJSDocTag<T extends JSDocTag>(kind: T["kind"], tagName: string): T {
+    export function createJSDocAugmentsTag(tagName: string, classExpression: JSDocAugmentsTag["class"], comment?: string) {


tagName should be limited to "augments" | "extends"

Klaus Meinhardt (ajafff) · 2019-01-24T11:07:23Z

+        return node;
+    }
+
+    export function createJSDocClassTag(tagName: string, comment?: string) {


is the tagName parameter necessary? it should always be "class"

Klaus Meinhardt (ajafff) · 2019-01-24T19:32:54Z

+
+    function createJSDocTagWithTypeExpression<T extends JSDocTag & { typeExpression?: TypeNode }>(kind: T["kind"], tagName: string, typeExpression?: TypeNode, comment?: string) {
+        const node = createJSDocTag<T>(kind, tagName, comment);
+        node.typeExpression = typeExpression;


AFAIK the factory functions should set properties in the same order as the parser to avoid multiple shapes of the same object.
Looking at parseReturnTag as an example: it sets tagName, typeExpression and comment (in parseTag function).

Maybe you want to change the parser to initialize the properties in the same order as the newly added factories (comment before typeExpression and so on)

In fact, I also have concerns about this, I decide to remove this helper function.😢

Wenlu Wang (Kingwl) · 2019-03-04T09:15:13Z

⬆️

Wenlu Wang (Kingwl) · 2019-03-21T04:48:39Z

🙋🏻‍♂️

Sheetal Nandi (sheetalkamat) · 2019-03-21T16:05:30Z

Daniel Rosenwasser (@DanielRosenwasser) Ryan Cavanaugh (@RyanCavanaugh) Ron Buckton (@rbuckton) Please take a look at this change as the issue is not marked as help wanted and is suggestion so not sure if we agreed/discussed if this is right approach.

ZHAO Jin-Xiang (xiaoxiangmoe) · 2019-11-24T07:41:48Z

Nathan Shively-Sanders (@sandersn) Daniel Rosenwasser (@DanielRosenwasser) Ryan Cavanaugh (@RyanCavanaugh) any update?

ZHAO Jin-Xiang (xiaoxiangmoe) · 2020-04-14T05:11:18Z

Any update？Daniel Rosenwasser (@DanielRosenwasser) Ryan Cavanaugh (@RyanCavanaugh) Ron Buckton (@rbuckton) Nathan Shively-Sanders (@sandersn)

Wenlu Wang (Kingwl) · 2020-04-14T05:18:34Z

Could we push this down (after 3.9 release)? it's useful for the code generator.

This reverts commit 76937c3.

Nathan Shively-Sanders (sandersn)

Seems like a fine idea to me, although I'll let Ron Buckton (@rbuckton) have veto power.

However, I don't think we should ship this until 4.0 since we're in 3.9 beta. Wenlu Wang (@Kingwl) are you OK with this, or did I misinterpret your comment?

Nathan Shively-Sanders (sandersn) · 2020-04-15T21:37:19Z

+        return createJSDocPropertyLikeTag<JSDocPropertyTag>(SyntaxKind.JSDocPropertyTag, "param", typeExpression, name, isNameFirst, isBracketed, comment);
+    }
+
+    export function createJSDocParameterTag(typeExpression: JSDocTypeExpression | undefined, name: EntityName, isNameFirst: boolean, isBracketed: boolean, comment?: string) {


why have both createJSDocParameterTag and createJSDocParamTag. The only real difference is that this sets isNameFirst but createJSDocParamTag doesn't.

Naively, it feels to me like we should only have one, which uses this code but is named createJSDocParamTag.

Well, except that we shouldn't break the API unnecessarily. Ugh. Can you add documentation saying that createJSDocParamTag is deprecated and that this is the preferred function now?

Nathan Shively-Sanders (sandersn) · 2020-04-15T21:37:28Z

+        return tag;
+    }
+
+    export function createJSDocImplementTag(classExpression: JSDocImplementsTag["class"], comment?: string) {


Suggested change

export function createJSDocImplementTag(classExpression: JSDocImplementsTag["class"], comment?: string) {

export function createJSDocImplementsTag(classExpression: JSDocImplementsTag["class"], comment?: string) {

Wenlu Wang (Kingwl) · 2020-04-16T01:34:00Z

Nope, please feel free to this.

Wenlu Wang (Kingwl) · 2020-04-16T06:15:38Z

Squash those comments please if someone going to merge.

Wenlu Wang (Kingwl) · 2020-04-17T16:44:04Z

TypeScript Bot (@typescript-bot) pack this.

TypeScript Bot (typescript-bot) · 2020-04-17T16:44:09Z

Heya Wenlu Wang (@Kingwl), I've started to run the tarball bundle task on this PR at e577f7e. You can monitor the build here.

TypeScript Bot (typescript-bot) · 2020-04-17T17:00:52Z

Hey Wenlu Wang (@Kingwl), I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/71483/artifacts?artifactName=tgz&fileId=3D437B95C52938407C7DBC39328F88EB27ABDA3C5150703D9DD87AD0F01F32E602&fileName=/typescript-3.9.0-insiders.20200417.tgz"
    }
}

and then running npm install.

There is also a playground for this build.

Wenlu Wang (Kingwl) · 2020-04-26T07:54:42Z

up plz :XD

Ron Buckton (rbuckton) · 2020-05-07T01:23:01Z

Unfortunately there is some overlap between this PR and #35282 as I also have all of these methods on the new NodeFactory API and I'm deprecating any factory-like methods exposed directly on the ts namespace.

expose jsdoc factory

2265a51

Wenlu Wang (Kingwl) mentioned this pull request Jan 23, 2019

Support jsdoc syntax HearTao/ts-creator#1

Open

Klaus Meinhardt (ajafff) reviewed Jan 23, 2019

View reviewed changes

refactor jsdoc factory

868fce5

Klaus Meinhardt (ajafff) reviewed Jan 24, 2019

View reviewed changes

correctly jsdoc factory types

6ea2418

Klaus Meinhardt (ajafff) reviewed Jan 24, 2019

View reviewed changes

update jsdoc factory

1cfa651

Sheetal Nandi (sheetalkamat) requested review from Daniel Rosenwasser (DanielRosenwasser) and Ron Buckton (rbuckton) March 21, 2019 16:03

Wenlu Wang (Kingwl) mentioned this pull request Apr 1, 2019

add refactor of extract type #30562

Merged

10 tasks

Ryan Cavanaugh (RyanCavanaugh) assigned Nathan Shively-Sanders (sandersn) Aug 15, 2019

Nathan Shively-Sanders (sandersn) added the For Backlog Bug PRs that fix a backlog bug label Feb 1, 2020

Nathan Shively-Sanders (sandersn) added For Uncommitted Bug PR for untriaged, rejected, closed or missing bug and removed For Backlog Bug PRs that fix a backlog bug labels Mar 26, 2020

Add check for delete expression must be optional

76937c3

Wenlu Wang (Kingwl) added 5 commits April 14, 2020 13:51

Merge branch 'master' into expose-jsdoc-factory

b536776

accept new basseline

5a76afe

Revert "Add check for delete expression must be optional"

2285fa3

This reverts commit 76937c3.

remove newline

6c4b439

make linter happy

61e16d4

Nathan Shively-Sanders (sandersn) approved these changes Apr 15, 2020

View reviewed changes

Add deprecated comment

e577f7e

Nathan Shively-Sanders (sandersn) added 2 commits May 6, 2020 11:39

Merge branch 'master' into expose-jsdoc-factory

d5dfc2a

Merge branch 'master' into expose-jsdoc-factory

31bf102

Nathan Shively-Sanders (sandersn) merged commit e66ce87 into microsoft:master May 6, 2020

Wenlu Wang (Kingwl) deleted the expose-jsdoc-factory branch May 7, 2020 00:46

github-actions Bot mentioned this pull request May 26, 2025

Bump astral-sh/setup-uv from 6.0.1 to 6.1.0 some-natalie/jekyll-in-a-can#16

Merged

github-actions Bot mentioned this pull request Sep 2, 2025

Bump astral-sh/setup-uv from 6.6.0 to 6.6.1 some-natalie/jekyll-in-a-can#48

Merged

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

	export function createJSDocImplementTag(classExpression: JSDocImplementsTag["class"], comment?: string) {
	export function createJSDocImplementsTag(classExpression: JSDocImplementsTag["class"], comment?: string) {

Uh oh!

Conversation

Wenlu Wang (Kingwl) commented Jan 23, 2019

Uh oh!

Klaus Meinhardt (ajafff) left a comment

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!

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!

Wenlu Wang (Kingwl) Jan 25, 2019 • 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!

Wenlu Wang (Kingwl) commented Mar 4, 2019

Uh oh!

Wenlu Wang (Kingwl) commented Mar 21, 2019

Uh oh!

Sheetal Nandi (sheetalkamat) commented Mar 21, 2019

Uh oh!

ZHAO Jin-Xiang (xiaoxiangmoe) commented Nov 24, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZHAO Jin-Xiang (xiaoxiangmoe) commented Apr 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Wenlu Wang (Kingwl) commented Apr 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Nathan Shively-Sanders (sandersn) left a comment

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!

Wenlu Wang (Kingwl) commented Apr 16, 2020

Uh oh!

Wenlu Wang (Kingwl) commented Apr 16, 2020

Uh oh!

Wenlu Wang (Kingwl) commented Apr 17, 2020

Uh oh!

TypeScript Bot (typescript-bot) commented Apr 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TypeScript Bot (typescript-bot) commented Apr 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Wenlu Wang (Kingwl) commented Apr 26, 2020

Uh oh!

Ron Buckton (rbuckton) commented May 7, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Wenlu Wang (Kingwl) Jan 25, 2019 •

edited

Loading

ZHAO Jin-Xiang (xiaoxiangmoe) commented Nov 24, 2019 •

edited

Loading

ZHAO Jin-Xiang (xiaoxiangmoe) commented Apr 14, 2020 •

edited

Loading

Wenlu Wang (Kingwl) commented Apr 14, 2020 •

edited

Loading

TypeScript Bot (typescript-bot) commented Apr 17, 2020 •

edited

Loading

TypeScript Bot (typescript-bot) commented Apr 17, 2020 •

edited

Loading