Skip to content

Clarify MidpointRounding docs: round-to-nearest vs directed rounding#12875

Open
tannergooding with Copilot wants to merge 2 commits into
mainfrom
copilot/improve-midpoint-rounding-docs
Open

Clarify MidpointRounding docs: round-to-nearest vs directed rounding#12875
tannergooding with Copilot wants to merge 2 commits into
mainfrom
copilot/improve-midpoint-rounding-docs

Conversation

Copilot AI commented Jul 11, 2026

Copy link
Copy Markdown
Contributor

The MidpointRounding name implies every mode only affects midpoints, but three of its five modes (ToNegativeInfinity, ToPositiveInfinity, ToZero) are directed-rounding modes that round every value in a fixed direction. Resolves dotnet/runtime#38160, which covers the current docs bury this distinction and the individual field summaries don't call it out.

Changes to xml/System/MidpointRounding.xml:

  • Type remarks: Added an upfront note that despite the enum name not every mode is midpoint-only, followed by a two-bullet summary contrasting the round-to-nearest and directed strategies before the existing per-strategy sections.
  • Directed rounding section: Reworded to explicitly state these modes apply to every input, with a concrete example (ToPositiveInfinity rounds 2.1, 2.5, and 2.8 all up to 3).
  • AwayFromZero / ToEven summaries: Noted that non-midpoint values are rounded to nearest regardless of the choice; added "banker's rounding" alias for ToEven.
  • ToNegativeInfinity / ToPositiveInfinity / ToZero summaries: Made explicit that every value (not just midpoints) is rounded in the given direction, and referenced the familiar equivalents (floor, ceiling, truncation).

@tannergooding tannergooding marked this pull request as ready for review July 11, 2026 22:49
@tannergooding tannergooding requested a review from a team as a code owner July 11, 2026 22:49
Copilot AI review requested due to automatic review settings July 11, 2026 22:49

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

This PR clarifies the documentation for System.MidpointRounding by explicitly distinguishing round-to-nearest modes (only differ at midpoints) from directed rounding modes (apply to all values), addressing confusion stemming from the enum’s name.

Changes:

  • Adds an upfront explanation in the type remarks contrasting round-to-nearest vs directed rounding.
  • Strengthens the directed-rounding section with explicit “applies to every value” wording and a concrete example.
  • Updates individual enum-field summaries to call out midpoint vs non-midpoint behavior and adds common aliases (e.g., “banker’s rounding”).
Show a summary per file
File Description
xml/System/MidpointRounding.xml Refines the enum remarks and field summaries to better explain which modes affect only midpoints vs all values.

Copilot's findings

  • Files reviewed: 1/1 changed files
  • Comments generated: 6

Comment thread xml/System/MidpointRounding.xml Outdated
Comment thread xml/System/MidpointRounding.xml Outdated
Comment thread xml/System/MidpointRounding.xml Outdated
Comment thread xml/System/MidpointRounding.xml Outdated
Comment thread xml/System/MidpointRounding.xml Outdated
Comment thread xml/System/MidpointRounding.xml Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Math.Round and misunderstanding

3 participants