GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — [Salsa] Support @typedef for jsdoc by zhengbli · Pull Request #8103 · microsoft/TypeScript

Conversation

@zhengbli

@zhengbli Zhengbo Li (zhengbli) commented Apr 15, 2016

Copy link
Copy Markdown

This PR adds support for the @typedef JSDoc tag. The current implementation includes the following formats:

Format 1:

/** @typedef { [Type Expression] } [Type Name] */

Format 2:

/** @typedef  [Type Expression] */
var [Type Name];

Format 3:

/** 
  * @typedef  {Object} [Type Name] 
  * @property {[Type Expression]} [Property Name]
  * @property {[Type Expression]} [Property Name]
  * ...
  */

Format 4:

/** 
  * @typedef  [Type Name] 
  * @type {Object}
  * @property {[Type Expression]} [Property Name]
  * @property {[Type Expression]} [Property Name]
  * ...
  */

Current the "Type name" can only be an identifier. Dotted names (qualified names) support may be added in future updates. The types defined by the @typedef tag are the same as type aliases in TypeScript, and they have scopes as well.

Basic support in language services like go to definition and rename is added as well.

Fixes #6976

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

d4rkr00t, johnfn, basarat, MarcioMonego, yajamon, svieira, Thaina, and techird reacted with thumbs up emoji Draggha reacted with hooray emoji
All reactions
  • 👍 8 reactions
  • 🎉 1 reaction
zhengbli and others added 6 commits April 3, 2016 11:52
zhengbli Zhengbo Li
Simple case and scoping
df91ef0
Zhengbo Li Zhengbo Li
Support the case with @Property and @type
23bca4e
Zhengbo Li Zhengbo Li
Support the case with variable name as @typedef type name
9a8f639
zhengbli
Add tests for renaming and incremental parsing. Changed how the AST w…
2945f64
…as hydrated

with jsdocComment nodes.
zhengbli
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
a3d74ad
… typedefForJsdoc

# Conflicts:
#	src/compiler/diagnosticMessages.json
#	src/services/services.ts
zhengbli
code clean up
0dddcf4
@msftclas Microsoft Contribution License Agreements (msftclas) added the cla-not-required label Apr 15, 2016
@zhengbli

Zhengbo Li (zhengbli) commented Apr 18, 2016

Copy link
Copy Markdown
Author

Ryan Cavanaugh (@RyanCavanaugh) Vladimir Matveev (@vladima) Mohamed Hegazy (@mhegazy) comments?

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

yuit
yuit reviewed Apr 19, 2016
View reviewed changes
Comment thread src/compiler/types.ts
JSDocTemplateTag,
JSDocTypedefTag,
JSDocPropertyTag,
JSDocTypeLiteral,

@yuit Yui (yuit) Apr 19, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: what is the JSDocTypeLiteral?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@zhengbli Zhengbo Li (zhengbli) Apr 19, 2016

Copy link
Copy Markdown
Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A @typedef is similar to a type alias in TS. In TS you can give an alias to an object type literal:

type T = { name: string, age: number}

which is equivalent to the following jsdoc:

/** 
 * @typedef {Object} T
 * @property {string} name
 * @property {number} age
 */

So I defined the @propertys as JSDocTypeLiteral, as it functions like object type literal, but with a different shape.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@billti

Bill Ticehurst (billti) commented Apr 19, 2016

Copy link
Copy Markdown
Member

Adding cross-reference to #7758

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

yuit
yuit reviewed Apr 19, 2016
View reviewed changes
Comment thread src/services/services.ts Outdated
scanner.setText((sourceFile || this.getSourceFile()).text);
children = [];
let pos = this.pos;
const useJSDocScanner =

@yuit Yui (yuit) Apr 19, 2016 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why don't u check like this : const useJSDocScanner = isJSDoc(this)? actaully question: why you don't use JSDocScanner on other JSDoc that is not listed here?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@zhengbli Zhengbo Li (zhengbli) Apr 19, 2016

Copy link
Copy Markdown
Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JSDocScanner limits scanning to several allowed characters, while disallowed characters are all scanned as unknown tokens. JSDoc nodes include JSDoc type nodes and JSDoc type expression nodes, and if the current position is inside a JSDoc type expression, it should allow all characters, because that part is essentially the same as code. For example, the < and > are not allowed in JSDoc tokens, they are fine when used with generics in JSDoc type expression.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@RyanCavanaugh

Ryan Cavanaugh (RyanCavanaugh) commented Apr 19, 2016

Copy link
Copy Markdown
Member

What's the perf impact of parsing the extra comments? Any?

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

yuit
yuit reviewed Apr 19, 2016
View reviewed changes
Comment thread src/services/utilities.ts Outdated
if (includeJsDocComment) {
const jsDocChildren = ts.filter(current.getChildren(), isJSDocNode);
for (const jsDocChild of jsDocChildren) {
let start = allowPositionInLeadingTrivia ? jsDocChild.getFullStart() : jsDocChild.getStart(sourceFile, includeJsDocComment);

@yuit Yui (yuit) Apr 19, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be "const"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
zhengbli added 4 commits April 22, 2016 14:26
zhengbli
refactor
15cbb02
zhengbli
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
870fd84
… typedefForJsdoc
zhengbli
resolve build error
d568d79
Zhengbo Li
Fix broken test
79bb4ba
@zhengbli

Zhengbo Li (zhengbli) commented Apr 25, 2016 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Author

I ran the following sample for the perf bench mark:

The Setup:

In an empty folder, do

npm install ember-cli

(I chose ember-cli because it is big enough to see the bind/parsing time difference)
then create an empty jsconfig.json with the following content:

{
    "exclude": []
}

The bench mark script is:

Write-Output "TSC runs:"
0..10 | % {tsc -p ".\jsconfig.json" --noEmit --diagnostics | Select-String "Bind Time|Parse Time"}

Write-Output "PR runs:"
0..10 | % { node --max-old-space-size=2000 "C:\Users\lizhe\Documents\github\TypeScript\built\local\tsc.js" -p ".\jsconfig.json" --noEmit --diagnostics | Select-String "Bind Time|Parse Time"}

The Result:

perf

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

zhengbli
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
9ff02b1
… typedefForJsdoc

# Conflicts:
#	src/services/services.ts
@zhengbli

Zhengbo Li (zhengbli) commented May 5, 2016 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Author

So it turns out that my previous benchmark wasn't very accurate at all, for several reasons:

  1. I was running the tests on a laptop on battery mode, and there are browsers / other background programs running at the same time
  2. The tsc.js for the PR was generated via calling jake local, which by default is in "debug mode", things like const enums are preserved for debugging purpose. I should instead use jake release local to generate the tsc.js.
  3. I used the command line tsc for the baseline, which may have node different parameters with what I used for the PR tests.
  4. On the PR I didn't pull from the latest master, so other changes may have impacted the results as well.

I rerun the benchmarks with these factors fixed. The new environment is:
a) a dedicated Ubuntu machine with no graphic interface (ssh)
b) a fresh installed windows 10 machine that is:

  • not domain-joined
  • no active tasks in task scheduler
  • desktop with high-performance power management options
  • as few background apps as possible (no onedrive, browser etc.)

c) use node for both cases, the new script is:

Param($count)

Write-Output "PR runs:"
0..($count - 1) | % { node --max-old-space-size=2000 "C:\Users\lan\Documents\github\TypeScript\built\local\tsc.js" -p ".\jsconfig.json" --noEmit --diagnostics | Select-String "Bind Time"}

Write-Output "Master runs:"
0..($count - 1) | % { node --max-old-space-size=2000 "C:\Program Files\nodejs\node_modules\typescript\lib\tsc.js" -p ".\jsconfig.json" --noEmit --diagnostics | Select-String "Bind Time" }

d) use the latest nightly and merge the PR with master locally. Checked the diff of two tsc.js files to make sure that the only differences are indeed caused by the PR.

And the benchmark result shows that the PR is not slower in binding time:

a) on the Ubuntu machine:
image
image

b) on the Windows machine:
win
image

AbraaoAlves, SergioMorchon, and styfle reacted with heart emoji
All reactions
  • ❤️ 3 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@RyanCavanaugh

Ryan Cavanaugh (RyanCavanaugh) commented May 5, 2016

Copy link
Copy Markdown
Member

👍 especially if it's somehow faster 😉

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

zhengbli added 3 commits May 24, 2016 21:06
zhengbli
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
5f9fa69
… typedefForJsdoc

# Conflicts:
#	src/services/services.ts
#	tests/cases/unittests/jsDocParsing.ts
zhengbli
Change how typedef tag is parsed
81ce532
zhengbli
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
e69976c
… typedefForJsdoc

# Conflicts:
#	src/services/utilities.ts
@zhengbli
Zhengbo Li (zhengbli) force-pushed the typedefForJsdoc branch from 95fd3a1 to e69976c Compare May 26, 2016 21:50
mhegazy
mhegazy reviewed May 26, 2016
View reviewed changes
Comment thread src/compiler/types.ts Outdated

// @kind(SyntaxKind.JSDocTypedefTag)
export interface JSDocTypedefTag extends JSDocTag, Declaration {
name: Identifier;

@mhegazy Mohamed Hegazy (mhegazy) May 26, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

name, typeExpresion and type should be optional.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@mhegazy

Mohamed Hegazy (mhegazy) commented May 26, 2016

Copy link
Copy Markdown
Contributor

I would add a navigate to test for typedefs

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

zhengbli added 4 commits May 30, 2016 22:11
zhengbli
cr feedback
18ee4b0
zhengbli
Add navigationTo test for jsdoc typedef
59b188d
Zhengbo Li
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
5261467
… typedefForJsdoc
Zhengbo Li
Fix broken test
e93f9df
@mhegazy

Mohamed Hegazy (mhegazy) commented May 31, 2016

Copy link
Copy Markdown
Contributor

👍

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@mhegazy

Mohamed Hegazy (mhegazy) commented May 31, 2016

Copy link
Copy Markdown
Contributor

#8849 touches the same areas, can you merge this in after that ones goes in.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

This was referenced May 31, 2016
Add jsdoc nodes to fixupParentReferences function #8702
Closed
Jsdoc @template issue in syntactic classifier #8676
Closed
zhengbli added 3 commits May 31, 2016 14:02
zhengbli
Merge branch 'outerControlFlows' of https://github.com/Microsoft/Type…
241920c
…Script into typedefForJsdoc

# Conflicts:
#	src/compiler/binder.ts
zhengbli
Merge branch 'master' of https://github.com/Microsoft/TypeScript into…
630517b
… typedefForJsdoc
zhengbli
Remove unused parameter
eb0f035
@zhengbli
Zhengbo Li (zhengbli) merged commit 166f399 into microsoft:master May 31, 2016
@zhengbli
Zhengbo Li (zhengbli) deleted the typedefForJsdoc branch May 31, 2016 23:24
@mhegazy Mohamed Hegazy (mhegazy) mentioned this pull request Jun 9, 2016
[IntelliSense] [Salsa] Support @callback in JSDoc #7515
Closed
@GRiMe2D Shakhzod Ikromov (GRiMe2D) mentioned this pull request Jul 10, 2016
Allow custom object types in JSDoc #9276
Closed
@zhengbli Zhengbo Li (zhengbli) mentioned this pull request Jul 11, 2016
Object member type defined by JSDoc @property tags are not recoganized #9620
Closed
@microsoft Microsoft (microsoft) locked and limited conversation to collaborators Jun 19, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

No reviews

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

6 participants

@zhengbli @billti @RyanCavanaugh @mhegazy @yuit @msftclas
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.