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

lib/*.d.ts の宣言を確認し、その JSDoc コメントからエラーをスローする可能性のあるメソッドを探します。Issue にある JSON パースの例を参考にして、該当する各メソッドが対応するエラーを @throws でドキュメント化していることを確認します。テストファイルや、より限定されたエントリーポイントは指定されていません。関連する宣言に一貫してアノテーションが付いていれば完了です。