docs(linter): update no-unsafe-type-assertion to reflect correct rule behavior (#16646)

Fixes oxc-project/tsgolint#492

Author: camc314

crates/oxc_linter/src/rules/typescript/no_unsafe_type_assertion.rs

@@ -8,50 +8,38 @@ pub struct NoUnsafeTypeAssertion;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// This rule disallows type assertions using the `any` type.
+    /// Disallows unsafe type assertions that narrow a type.
     ///
     /// ### Why is this bad?
     ///
-    /// Type assertions using `any` completely bypass TypeScript's type system and can lead to runtime errors. They should be avoided in favor of more specific type assertions or proper type guards.
+    /// Type assertions that narrow a type bypass TypeScript's type-checking and can lead to
+    /// runtime errors. Type assertions that broaden a type are safe because TypeScript
+    /// essentially knows *less* about a type. Instead of using type assertions to narrow a
+    /// type, it's better to rely on type guards, which help avoid potential runtime errors
+    /// caused by unsafe type assertions.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```ts
-    /// declare const value: unknown;
-    ///
-    /// const str = value as any; // unsafe type assertion
-    ///
-    /// const obj = value as any as string; // double assertion through any
-    ///
-    /// function processValue(input: unknown) {
-    ///   const processed = input as any; // unsafe
-    ///   return processed.someProperty;
+    /// function f() {
+    ///   return Math.random() < 0.5 ? 42 : 'oops';
     /// }
+    /// const z = f() as number;
+    ///
+    /// const items = [1, '2', 3, '4'];
+    /// const number = items[0] as number;
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```ts
-    /// declare const value: unknown;
-    ///
-    /// // Use specific type assertions
-    /// const str = value as string; // more specific assertion
-    ///
-    /// // Use type guards
-    /// if (typeof value === 'string') {
-    ///   const str2 = value; // safe, no assertion needed
-    /// }
-    ///
-    /// // Use proper interface assertions
-    /// interface User {
-    ///   name: string;
-    ///   age: number;
+    /// function f() {
+    ///   return Math.random() < 0.5 ? 42 : 'oops';
     /// }
+    /// const z = f() as number | string | boolean;
     ///
-    /// const user = value as User; // specific type assertion
-    ///
-    /// // Use unknown for truly unknown values
-    /// const unknown: unknown = value;
+    /// const items = [1, '2', 3, '4'];
+    /// const number = items[0] as number | string | undefined;
     /// ```
     NoUnsafeTypeAssertion(tsgolint),
     typescript,