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

Kingwl · 2019-01-23T10:21:56Z

ajafff

Do you plan on adding the corresponding updateJSDocXXX functions?

ajafff · 2019-01-23T11:50:28Z

src/compiler/factory.ts

    }

+    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

ajafff · 2019-01-23T11:50:58Z

src/compiler/factory.ts

-    /* @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: @DanielRosenwasser

ajafff · 2019-01-23T11:52:28Z

src/compiler/factory.ts

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


prefer classExpression: JSDocAugmentsTag['class']

ajafff · 2019-01-23T11:53:14Z

src/compiler/factory.ts

+    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

ajafff · 2019-01-24T08:51:30Z

src/compiler/factory.ts

+        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?

ajafff · 2019-01-24T09:12:57Z

src/compiler/factory.ts

+        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

ajafff · 2019-01-24T11:06:58Z

src/compiler/factory.ts


-    /* @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"

ajafff · 2019-01-24T11:07:23Z

src/compiler/factory.ts

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


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

ajafff · 2019-01-24T19:32:54Z

src/compiler/factory.ts

+
+    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.😢

Kingwl · 2019-03-04T09:15:13Z

⬆️

Kingwl · 2019-03-21T04:48:39Z

🙋🏻‍♂️

sheetalkamat · 2019-03-21T16:05:30Z

@DanielRosenwasser @RyanCavanaugh @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.

xiaoxiangmoe · 2019-11-24T07:41:48Z

@sandersn @DanielRosenwasser @RyanCavanaugh any update?

xiaoxiangmoe · 2020-04-14T05:11:18Z

Any update？@DanielRosenwasser @RyanCavanaugh @rbuckton @sandersn

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.

sandersn

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

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

sandersn · 2020-04-15T21:37:19Z

src/compiler/factoryPublic.ts

+        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?

sandersn · 2020-04-15T21:37:28Z

src/compiler/factoryPublic.ts

+        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) {

Kingwl · 2020-04-16T01:34:00Z

Nope, please feel free to this.

Kingwl · 2020-04-16T06:15:38Z

Squash those comments please if someone going to merge.

Kingwl · 2020-04-17T16:44:04Z

@typescript-bot pack this.

typescript-bot · 2020-04-17T16:44:09Z

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

typescript-bot · 2020-04-17T17:00:52Z

Hey @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.

Kingwl · 2020-04-26T07:54:42Z

up plz :XD

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

Kingwl mentioned this pull request Jan 23, 2019

Support jsdoc syntax HearTao/ts-creator#1

Open

ajafff reviewed Jan 23, 2019

View reviewed changes

refactor jsdoc factory

868fce5

ajafff reviewed Jan 24, 2019

View reviewed changes

correctly jsdoc factory types

6ea2418

ajafff reviewed Jan 24, 2019

View reviewed changes

update jsdoc factory

1cfa651

sheetalkamat requested review from DanielRosenwasser and rbuckton March 21, 2019 16:03

Kingwl mentioned this pull request Apr 1, 2019

add refactor of extract type #30562

Merged

10 tasks

RyanCavanaugh assigned sandersn Aug 15, 2019

sandersn added the For Backlog Bug PRs that fix a backlog bug label Feb 1, 2020

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

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

sandersn approved these changes Apr 15, 2020

View reviewed changes

Add deprecated comment

e577f7e

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

sandersn merged commit e66ce87 into microsoft:master May 6, 2020

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 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) {

Conversation

Kingwl commented Jan 23, 2019

Uh oh!

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!

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!

Kingwl commented Mar 4, 2019

Uh oh!

Kingwl commented Mar 21, 2019

Uh oh!

sheetalkamat commented Mar 21, 2019

Uh oh!

xiaoxiangmoe commented Nov 24, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xiaoxiangmoe commented Apr 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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!

Kingwl commented Apr 16, 2020

Uh oh!

Kingwl commented Apr 16, 2020

Uh oh!

Kingwl commented Apr 17, 2020

Uh oh!

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 commented Apr 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kingwl commented Apr 26, 2020

Uh oh!

rbuckton commented May 7, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Kingwl Jan 25, 2019 •

edited

Loading

xiaoxiangmoe commented Nov 24, 2019 •

edited

Loading

xiaoxiangmoe commented Apr 14, 2020 •

edited

Loading

Kingwl commented Apr 14, 2020 •

edited

Loading

typescript-bot commented Apr 17, 2020 •

edited

Loading

typescript-bot commented Apr 17, 2020 •

edited

Loading