Skip to content

docs: fix stale README + guides — plural factories, V3 object-init, real PhysicalConstants surface#76

Merged
matt-edmondson merged 1 commit intovectorsfrom
claude/docs-fix-vector-examples
May 10, 2026
Merged

docs: fix stale README + guides — plural factories, V3 object-init, real PhysicalConstants surface#76
matt-edmondson merged 1 commit intovectorsfrom
claude/docs-fix-vector-examples

Conversation

@matt-edmondson
Copy link
Copy Markdown
Contributor

Summary

Pure docs sync — no code or generated output changes. Fixes three user-facing docs that drifted from the actual generator output. Independent of #75 (which only touches *.cs/*.json/Generated/CLAUDE.md), so they should land cleanly together.

What was wrong

  1. README.md had aspirational PhysicalConstants.Conversion.X<T>() accessors that were never emitted. CLAUDE.md was cleaned up for this in feat(generator): SEM002 metadata validation + refresh stale generator output #70 but README wasn't.
  2. README.md, docs/physics-domains-guide.md, docs/complete-library-guide.md showed V3 construction via 3-arg Force3D<double>.FromNewtons(0.0, 0.0, -9.8) factories that don't exist — generated VN types only have Zero/One/UnitX/Y/Z static properties and object-initializer construction (new Force3D<double> { X = 0.0, Y = 0.0, Z = -9.8 }).
  3. docs/complete-library-guide.md had mass * Acceleration<double>.FromMeters(9.8) which is wrong on two counts: Acceleration is a dimension name (the generated V0 base type is AccelerationMagnitude), and Meters is the wrong unit for acceleration (MetersPerSecondSquared).
  4. README's disp3d.Magnitude() comment said it returned Distance — but Magnitude() returns the V0 base of the dimension (Length), not a semantic overload.

What changed

  • README.md — V3 examples switched to new T<double> { X, Y, Z }. PhysicalConstants examples replaced with the real domain-grouped + Generic<T>() surface. Architecture section now lists units.json / magnitudes.json / conversions.json / domains.json alongside dimensions.json, and the SEM001/SEM002/SEM003 diagnostic line-up. Construction-time invariants from Vector0 quantities do not enforce the non-negativity invariant #50/Domain-specific physical constraints (absolute zero, non-negative frequency, etc.) not enforced #51 added as a code comment.
  • docs/physics-domains-guide.md — Magnitude / Cross / Dot examples switched to object-initializer construction.
  • docs/complete-library-guide.md — same V3 fix; corrected the bogus Acceleration<double>.FromMeters(9.8) to AccelerationMagnitude<double>.FromMetersPerSecondSquared(9.8); Magnitude() comment corrected to Length not Distance.

Test plan

  • No code or Generated/ changes — diff is README.md, docs/physics-domains-guide.md, docs/complete-library-guide.md.
  • Examples were sanity-checked against the actual emitted types (Velocity3D.g.cs, Force3D.g.cs, Length.g.cs, etc.) and the PhysicalConstantsGenerator output to make sure every snippet would now compile.
  • No CI relevance beyond markdown rendering.

https://claude.ai/code/session_01Tj63Rddvs9frqLUgsjNEP5


Generated by Claude Code

…eal PhysicalConstants surface

Sweeps three user-facing docs to match the current generator output:

README.md
- V0 factory examples already correct on plural (FromMetersPerSecond,
  FromMeters, FromKilograms, FromNewtons, FromSeconds).
- V3 examples (Force3D, Displacement3D) switched from non-existent
  3-arg From{Unit}(x, y, z) factories to object-initializer
  construction with X/Y/Z components, which matches what the
  generator actually emits.
- Magnitude() example now says "Length" rather than "Distance" — the
  V3 base's Magnitude() returns the V0 base of the dimension, not an
  overload.
- Added a comment showing the construction-time invariants from
  #50/#51 (Speed.FromMetersPerSecond(-1) and
  Wavelength.FromMeters(0) both throw ArgumentException).
- Removed the aspirational PhysicalConstants.Conversion.X<T>()
  examples (CLAUDE.md was already cleaned up in #70 but README
  hadn't been). Replaced with the real domain-grouped /
  Generic<T>() shape that PhysicalConstantsGenerator emits today.
- Architecture section: now lists units.json/magnitudes.json/
  conversions.json/domains.json alongside dimensions.json and adds
  the SEM001/SEM002/SEM003 diagnostic line-up.

docs/physics-domains-guide.md
- Magnitude / Cross / Dot examples use object-initializer for V3,
  matching the generated surface.

docs/complete-library-guide.md
- Same V3 fix.
- "mass * Acceleration<double>.FromMeters(9.8)" was nonsense on two
  counts (Acceleration is a dimension name, not a generated type;
  Meters is the wrong unit for acceleration). Replaced with the
  correct AccelerationMagnitude<double>.FromMetersPerSecondSquared(9.8).
- Magnitude() example now says "Length" rather than "Distance"; same
  reason as the README fix.

No code or generated output changes; pure docs sync to current API.
@matt-edmondson matt-edmondson merged commit fffc635 into vectors May 10, 2026
1 check passed
@matt-edmondson matt-edmondson deleted the claude/docs-fix-vector-examples branch May 10, 2026 13:40
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.

2 participants