docs(dump_metrics): format_number comment claims a JSON trailing-.0 elision that serde_json does not do

[dekobon]

Summary

The inline comment in format_number claims its integer fast-path matches "the JSON serializer's trailing-.0 elision", but serde_json does not elide trailing .0 from f64 values — JSON output renders whole-valued floats with the .0 intact.

Location

• src/output/dump_metrics.rs:272-274

Evidence

// A safe-integer-valued float (e.g. an exact `2.0` average) prints as
// an integer, matching the JSON serializer's trailing-`.0` elision.
if float.fract() == 0.0 && float.abs() < F64_SAFE_INT_BOUND {
    #[allow(clippy::cast_possible_truncation)]
    return (float as i64).to_string();
}

serde_json (and serde's f64 serialization generally) always emits a decimal point for an f64: an f64 value of 2.0 serializes as 2.0, never 2. The metric JSON snapshots in this repo confirm whole-valued floats keep the .0:

src/metrics/snapshots/big_code_analysis__metrics__cognitive__tests__tcl_2_level_nesting.snap:  "n": 6.0,
src/metrics/snapshots/big_code_analysis__metrics__loc__tests__php_no_zero_blank.snap:  "sloc_n": 5.0,

So for a whole-valued average the dump prints 6 while the JSON output prints 6.0. The dump's behavior (printing 6) is the deliberate legibility choice documented in the module header ("float values render rounded ... whereas JSON keeps full precision"), and is fine. The problem is only the rationale: the comment asserts a JSON "trailing-.0 elision" that does not exist, which misleads a future reader into believing the two views agree on whole floats when they do not.

Expected Behavior

The comment should state the dump deliberately prints whole-valued floats without a decimal point for legibility, diverging from JSON, which keeps the .0.

Actual Behavior

The comment claims the integer fast-path matches a JSON "trailing-.0 elision" — describing JSON behavior that serde_json does not exhibit.

Impact

Documentation-only. A maintainer relying on the comment may incorrectly assume the text dump and JSON agree on whole-valued float rendering, or may "fix" a perceived JSON regression that is actually correct serde_json behavior. No runtime effect.

---

Resolution

Fixed in 7a41184: format_number comment now states the whole-float-as-integer rendering DIVERGES from JSON (a legibility choice), not matches it.

[dekobon]

General Plan for Fix

Root Cause

The comment was written under the mistaken belief that serde_json renders a whole-valued f64 (e.g. 2.0) without its decimal point. serde_json always emits 2.0 for an f64, so there is no "trailing-.0 elision" to match. The dump's integer fast-path is a deliberate divergence from JSON for terminal legibility, not a parity behavior.

Implementation Steps

1. Reword the inline comment at src/output/dump_metrics.rs:272-274 to state the truth: a safe-integer-valued float prints without a decimal point in the text dump for legibility, which diverges from JSON output (serde_json keeps the .0). Keep it consistent with the module header's "JSON keeps full precision" framing.

Tests to Add/Update

• No runtime change, so no new assertion is strictly required. Optionally add a one-line dump test asserting a whole-valued average renders without .0 (e.g. functions: 1 not 1.0) to pin the documented divergence — but this is a comment-only fix.

Verification

• cargo doc --no-deps -p big-code-analysis clean (comment is not a doc comment, but confirm no warnings)
• cargo test -p big-code-analysis passes
• Manual verification: the reworded comment no longer asserts a non-existent JSON elision; cross-check against an actual JSON snapshot ("n": 6.0) vs dump (n: 6).

[dekobon]

Fixed in 7a41184. The format_number comment claimed the integer fast-path matches "the JSON serializer's trailing-.0 elision," but serde_json does NOT elide .0 (2.0 serializes as "2.0"). Corrected the comment to state the truth: the dump prints whole floats as integers as a deliberate legibility choice that DIVERGES from JSON. Behavior unchanged.

[dekobon]

Fixed and merged to main in #957. GitHub did not auto-close this from the batched commit's single Fixes #a #b #c … trailer (only the first referenced issue auto-closes); closing manually. See the Resolution section in the body for details.