docs(lib): add @throws JSDoc for BigInt methods and constructor#61653
docs(lib): add @throws JSDoc for BigInt methods and constructor#61653Joseph-Martre wants to merge 2 commits intomicrosoft:mainfrom
Conversation
|
This PR doesn't have any linked issues. Please open an issue that references this PR. From there we can discuss and prioritise. |
Related to #43528 |
ArshVermaGit
left a comment
There was a problem hiding this comment.
This PR enhances the developer experience by adding @throws JSDoc annotations to the BigInt constructor and its methods, making potential runtime exceptions more visible through editor tooltips and generated documentation. Although the change does not affect runtime or type-checking behavior, it improves clarity and discoverability, especially for developers working across environments where understanding edge-case failures (such as invalid radix values or improper inputs) is important. The decision to avoid documenting the more contrived TypeError scenarios arising from misuse via .call or .apply feels sensible, keeping the documentation focused and signal-rich rather than overly verbose. Overall, this is a thoughtful documentation improvement that aligns well with TypeScript’s goals of being a practical, cross-platform tooling ecosystem while helping developers write more predictable and maintainable code.
Adds
@throwsJSDoc documentation to theBigIntconstructor and methods to clarify their potential error behavior.This helps developers better understand the runtime exceptions these methods may produce, and improves IDE support/documentation.
Related to #43528
Alignment with TypeScript Design Goals:
Test Criteria
This PR only introduces documentation changes in
.d.tsfiles.It does not affect runtime behavior or type system behavior, and therefore does not require test cases.
Note: Technically,
BigInt.prototype.toStringcan throw aTypeErrorif the value ofthisis not aBigInt, such as inBigInt.prototype.toString.call(nonBigIntValue, radix). However, this case is not included in the JSDoc. AddingTypeErrordocumentation for such misuse across prototype methods would introduce noise with limited practical benefit. This behavior is already well understood by developers using.call/.applypatterns on object prototype methods.