Skip to content

docs: rm error code example and add more practical one and change casts to type assertions #3621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
legend80s wants to merge 1 commit into
base: v2
Choose a base branch
from
Open

docs: rm error code example and add more practical one and change casts to type assertions #3621

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions packages/documentation/copy/en/javascript/JSDoc Reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,6 @@ var win;

/** @type {PromiseLike<string>} */
var promisedString;

// You can specify an HTML Element with DOM properties
/** @type {HTMLElement} */
var myElement = document.querySelector(selector);
element.dataset.myData = "";
```

`@type` can specify a union type &mdash; for example, something can be either a string or a boolean.
Expand Down Expand Up @@ -160,10 +155,11 @@ var star;
var question;
```

#### Casts
#### Type Assertions

TypeScript borrows cast syntax from Google Closure, using it as type assertions in JSDoc.

TypeScript borrows cast syntax from Google Closure.
This lets you cast types to other types by adding a `@type` tag before any parenthesized expression.
This lets you "cast" types to other types by adding a `@type` tag before any **parenthesized** expression like `as` keyword in TypeScript.

```js twoslash
/**
Expand All @@ -173,12 +169,30 @@ var numberOrString = Math.random() < 0.5 ? "hello" : 100;
var typeAssertedNumber = /** @type {number} */ (numberOrString);
```

A more practical and common use case is to assign a specific HTML element type for a element.

Sometimes you will have information about the type of a value that TypeScript can’t know about.

For example, if you’re using `document.getElementById`, TypeScript only knows that this will return *some* kind of `HTMLElement`, but you might know that your page will always have an `HTMLCanvasElement` with a given ID.

In this situation, you can use a *type assertion* to specify a more specific type:

```js twoslash
const myCanvas = /** @type {HTMLCanvasElement} */ (document.getElementById("main_canvas"));
```

You can even cast to `const` just like TypeScript:

```js twoslash
let one = /** @type {const} */(1);
```

The type assertions can be nested:

```js twoslash
const x = /** @type {number} */ (/** @type {unknown} */ ("hello"))
```

#### Import types

You can import declarations from other files using import types.
Expand Down