Float docs reference dozens of phantom Float.*/Math.* functions; many in inconsistent snake_case

[davidfrogley]

Summary

Web/src/docs/types/float.md advertises a large API surface on Float, Math/math, and float values themselves that is not implemented in Std/Src/Math.rux (or anywhere else in Std/Src/). Some of the references are in rendered sections; others are inside HTML-commented blocks but use the same nonexistent names and so will become broken docs the moment the comments are removed.

What the user noticed (rendered text)

Web/src/docs/types/float.md:

• L399-407 — "Best Practices" section recommends Float.approx_eq(0.1 + 0.2, 0.3). No such function exists. Doubly broken: the immediately-preceding "Approximate Equality" section that defined approx_eq is itself in an HTML comment (L360-388), so the recommendation refers to an example the reader will never see.
• L423-431 — "Best Practices" section recommends Math.Fma(a, b, c). No Fma in Std/Src/Math.rux. The "definition" snippet at L290 (math.fma(2.0, 3.0, 1.0)) is also fictitious and uses the wrong casing (math. vs Math.).

Compiler/stdlib reality (source of truth)

Std/Src/Math.rux defines exactly: Pi, E, Add(int,int), Sin, Cos, Tan, Sqrt, Pow, Abs, Floor, Ceil, Round (in float64 and most also in float32 overloads).

There is no Float module/type/namespace in Std/Src/ at all — IsNan/IsInfinite/ToString for float types live as top-level functions in module Std (see Std/Src/Float64.rux), not on a Float namespace.

Function names follow PascalCase (IsNan, ToString, Sqrt, etc.). Note IsNan, not IsNaN — the stdlib's own casing is uppercase-only on the first letter of each word, so even readers who try to fix the docs by changing case will land on the wrong identifier.

Bug 1 — Phantom functions in rendered sections

Web/src/docs/types/float.md:

• L351-358 — Float.IsNaN(value) — wrong namespace (Float. doesn't exist) and wrong casing (IsNaN vs the real IsNan). The real call is IsNan(value) (no receiver).
• L416 — same Float.IsNaN(result) mistake.
• L423-431 — Math.Fma(a, b, c) — no such function in Math.rux.
• L399-407 — Float.approx_eq(...) — doesn't exist (and is snake_case in a PascalCase API; see Bug 3).
  • L472-477 — let inf = Float.Inf; — Float.Inf doesn't exist. The arithmetic examples around it (inf + 1.0, inf - inf, etc.) work because they're plain operators, but the constant binding line itself won't compile.

Bug 2 — Phantom functions in HTML-commented sections

These don't render today but reuse the same nonexistent names, so uncommenting any of these blocks turns them into bugs in rendered output:

• L170-182 — Float.inf, Float.neg_inf, Float.nan, Float.is_nan, Float.is_infinite, Float.is_finite. Snake_case, no Float namespace.
• L222-235 — instance methods x.to_float64(), x.to_float128(), x.to_int32(), x.to_bits(), and the static float32.from_bits(...). None exist; also the to_float128 mentions a type the compiler doesn't implement (separate type-mismatch issue already filed).
• L275-308 — entire math.* block: math.sqrt, math.cbrt, math.abs, math.floor, math.ceil, math.round, math.trunc, math.fma, math.sin, math.cos, math.tan, math.atan2, math.exp, math.ln, math.log2, math.log10, math.sinh, math.cosh, math.tanh, plus constants math.PI and math.E. None of these match the actual module name (Std::Math) and most don't exist even after fixing the casing (not implemented yet).
• L361-388 — the snake_case approx_eq user function, then the Float.approx_eq / Float.approx_eq_eps claims, then Float.total_cmp, Float.NaN, Float.Inf, and values.sort_by(Float.total_cmp).
• L497-503 — import Float::Rounding and Float.Rounding.with_mode(.toward_zero) { … }.
• L508-513 — Float.nan, Float.signaling_nan.
• L515-526 — #[allow(fast_math)] attribute.
• L529-535 — import float.config; float.config.set_flush_to_zero(true).
• L538-544 — Float.to_le_bytes(), Float.to_be_bytes(), float32.from_le_bytes(...).

Bug 3 — Casing inconsistency throughout

The same docs flip between snake_case and PascalCase for what's allegedly the same API:

• PascalCase (matches stdlib convention): Float.IsNaN, Float.NaN, Float.Inf, Math.Fma.
• snake_case (does not match anything in stdlib): Float.is_nan, Float.is_infinite, Float.is_finite, Float.approx_eq, Float.approx_eq_eps, Float.total_cmp, Float.neg_inf, Float.nan, Float.signaling_nan, Float.to_le_bytes, Float.to_be_bytes, Float.from_le_bytes, float.config.set_flush_to_zero, all the math.* functions, to_float64, to_float128, to_int32, to_bits, from_bits, sort_by.

If the intended convention is PascalCase (which Std/Src/*.rux uses uniformly), every snake_case identifier in this file is wrong. If the intended convention is snake_case, then the stdlib itself is at odds with the docs and a much bigger decision is needed. Either way, the file is internally inconsistent.

A subtler point: even within the PascalCase camp, the docs use IsNaN while the stdlib uses IsNan. Pick one (and consider doing the same for Inf/Inf, Nan/NaN) so users don't have to guess.

Suggested fixes

1. Decide the casing convention. Almost certainly PascalCase, since that's what every existing Std/Src/*.rux file uses. Then sweep the float doc to
   match, including hidden snippets so they don't rot further.
2. Remove or gate phantom functions. For each function the doc references that doesn't exist in Std/Src/, either delete the mention or wrap it in a "Planned" / "Not yet implemented" callout. Don't leave Math.Fma-style recommendations in a "Best Practices" section that today amounts to "use this function that doesn't exist."
3. Decide where things live. The doc treats Float as a namespace (Float.IsNaN, Float.Inf) but the stdlib puts those at module-level (Std::IsNan, no Inf constant at all). Pick a story — top-level, sub-module, or methods on the float types — and align both.
4. Either add Float-namespaced constants/methods (Float.Inf, Float.NaN, Float.IsNaN, to_le_bytes, etc.) to the stdlib, or rewrite the doc to reflect that these don't exist. Currently the doc is the spec for an API that nobody has written.