Expect to use @throws in lib/*.d.ts to mark which methods may throw err

Suggestion

Use @throws to mark the corresponding error on the method in the .d.ts file in the lib directory

🔍 Search Terms

@throws jsdoc comments

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Use @throws to mark the corresponding error on the method in the .d.ts file in the lib directory

📃 Motivating Example

/**
 * Converts a JavaScript Object Notation (JSON) string into an object.
 * @param text A valid JSON string.
 * @param reviver A function that transforms the results. This function is called for each member of the object.
+* @throws {SyntaxError} if the string to parse is not valid JSON. 
 * If a member contains nested objects, the nested objects are transformed before the parent object is.
 */
 parse(text: string, reviver?: (this: any, key: string, value: any) => any): any;

💻 Use Cases

want to be able to write code when you know that you need to beware of these unpredictable behavior

Review the declarations in lib/*.d.ts and search their JSDoc comments for methods that can throw errors. Use the JSON parsing example in the issue as a reference, then verify that each applicable method documents its corresponding error with @throws. No test file or narrower entry point is named; done means the relevant declarations are consistently annotated.