docs: fix stale README + guides — plural factories, V3 object-init, real PhysicalConstants surface#76
Merged
matt-edmondson merged 1 commit intovectorsfrom May 10, 2026
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
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.Force3D<double>.FromNewtons(0.0, 0.0, -9.8)factories that don't exist — generated VN types only haveZero/One/UnitX/Y/Zstatic properties and object-initializer construction (new Force3D<double> { X = 0.0, Y = 0.0, Z = -9.8 }).mass * Acceleration<double>.FromMeters(9.8)which is wrong on two counts:Accelerationis a dimension name (the generated V0 base type isAccelerationMagnitude), andMetersis the wrong unit for acceleration (MetersPerSecondSquared).disp3d.Magnitude()comment said it returnedDistance— butMagnitude()returns the V0 base of the dimension (Length), not a semantic overload.What changed
new T<double> { X, Y, Z }.PhysicalConstantsexamples replaced with the real domain-grouped +Generic<T>()surface. Architecture section now listsunits.json/magnitudes.json/conversions.json/domains.jsonalongsidedimensions.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.Acceleration<double>.FromMeters(9.8)toAccelerationMagnitude<double>.FromMetersPerSecondSquared(9.8);Magnitude()comment corrected toLengthnotDistance.Test plan
Generated/changes — diff isREADME.md,docs/physics-domains-guide.md,docs/complete-library-guide.md.Velocity3D.g.cs,Force3D.g.cs,Length.g.cs, etc.) and thePhysicalConstantsGeneratoroutput to make sure every snippet would now compile.https://claude.ai/code/session_01Tj63Rddvs9frqLUgsjNEP5
Generated by Claude Code