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

[legend80s]

What's the problem of current docs?

1. Type error and Inappropriate example

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

1 element should be myElement

2 type error and misplaced Example

Type 'HTMLElement | null' is not assignable to type 'HTMLElement'.
  Type 'null' is not assignable to type 'HTMLElement'.

This example doesn't fit the first use case of @type — it's better suited for demonstrating casts. It should be removed from the first part of @type introduction.

It's a perfect example for cast:

// You can specify an HTML Element with DOM properties
const myElement = /** @type {HTMLElement} */ (
  document.querySelector("#selector")
)

myElement.dataset.myData = ""

No more errors and the inline usage of @type assertion is well explained.

2. Rename "Casts" to "Type Assertions"

It's functionally identical to TypeScript's as — simply written as inline @type in JSDoc!

C-style casts imply a runtime type conversion, whereas TypeScript's as syntax and JSDoc's inline @type are simply type assertions that do not affect runtime behavior. Thus, "Type Assertions" is a more accurate and less misleading term.

3. Add example from https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions

4. Add JSDoc equivalent for as unknown as T

The original docs don't show how to write nested inline assertions in JSDoc — a pattern many users don't know about.

const x = "hello" as unknown as number;

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

[legend80s]

@legend80s please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree

[legend80s]

@microsoft-github-policy-service agree