Skip to content

docs(lib): add @throws JSDoc for BigInt methods and constructor#61653

Open
Joseph-Martre wants to merge 2 commits intomicrosoft:mainfrom
Joseph-Martre:docs/jsdoc-bigint
Open

docs(lib): add @throws JSDoc for BigInt methods and constructor#61653
Joseph-Martre wants to merge 2 commits intomicrosoft:mainfrom
Joseph-Martre:docs/jsdoc-bigint

Conversation

@Joseph-Martre
Copy link
Copy Markdown
Contributor

@Joseph-Martre Joseph-Martre commented May 4, 2025

Adds @throws JSDoc documentation to the BigInt constructor 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:

  • (2) Provide a structuring mechanism for larger pieces of code.
  • (10) Be a cross-platform development tool.

Test Criteria

This PR only introduces documentation changes in .d.ts files.
It does not affect runtime behavior or type system behavior, and therefore does not require test cases.

Note: Technically, BigInt.prototype.toString can throw a TypeError if the value of this is not a BigInt, such as in BigInt.prototype.toString.call(nonBigIntValue, radix). However, this case is not included in the JSDoc. Adding TypeError documentation for such misuse across prototype methods would introduce noise with limited practical benefit. This behavior is already well understood by developers using .call/.apply patterns on object prototype methods.

@typescript-bot typescript-bot added the For Uncommitted Bug PR for untriaged, rejected, closed or missing bug label May 4, 2025
@github-project-automation github-project-automation bot moved this to Not started in PR Backlog May 4, 2025
@typescript-bot
Copy link
Copy Markdown
Collaborator

This PR doesn't have any linked issues. Please open an issue that references this PR. From there we can discuss and prioritise.

@Joseph-Martre
Copy link
Copy Markdown
Contributor Author

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

taewanHwang

This comment was marked as spam.

@RyanCavanaugh RyanCavanaugh added this to the Post-7.0 lib candidates milestone Mar 24, 2026
Copy link
Copy Markdown

@ArshVermaGit ArshVermaGit left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

For Uncommitted Bug PR for untriaged, rejected, closed or missing bug

Projects

Status: Not started

Development

Successfully merging this pull request may close these issues.

5 participants