Skip to content

Add worked example to dim-si README#6

Closed
dyreby wants to merge 2 commits intodocs/type-annotations-compound-unitsfrom
docs/worked-example
Closed

Add worked example to dim-si README#6
dyreby wants to merge 2 commits intodocs/type-annotations-compound-unitsfrom
docs/worked-example

Conversation

@dyreby
Copy link

@dyreby dyreby commented Feb 12, 2026

Add a "Worked Example" section showing a complete kinetic energy calculation (KE = ½mv²).

Demonstrates:

  • Typed function with Quantity<Mass>, Quantity<Velocity>, Quantity<Energy>
  • Cross-dimension arithmetic (multiply, scale)
  • Unit conversion (valueIn with joule/kilojoule)
  • Compile-time error for dimension mismatches

Stacked on #5 — merge that first.

Closes #8

Show a complete kinetic energy calculation with typed functions,
demonstrating dimensional analysis catching errors in context.

Addresses #4
@dyreby dyreby added documentation Improvements or additions to documentation pkg:dim-si dim-si package labels Feb 12, 2026
@dyreby dyreby requested a review from gdtroszak February 12, 2026 20:50
@gdtroszak
Copy link
Contributor

A few concerns with this PR as-is:

  • Fluent vs free functions: The Quick Start showcases the q() fluent API, but this worked example uses only free functions (multiply, scale). This sends mixed signals about the preferred style and feels like a step backward from what the Quick Start already demonstrates.
  • Import inconsistency: Types are imported from @isentropic/dim-isq directly, but the Type Annotations section (PR Add type annotation and compound unit docs to dim-si README #5) imports them from @isentropic/dim-si/* re-exports. Users will wonder which is correct.
  • Redundancy: The example mostly re-demonstrates concepts already covered in the Quick Start (unit creation, arithmetic, conversions, compile-time errors) without adding much new.

Rather than a separate worked example, I think the better move is to expand the Quick Start to show more operations (multiplication, division, scaling) using the fluent API. I have pushed a commit to this branch that does that and removes the worked example section. The free functions get a one-line mention instead of a code block.

Please take a look and let me know what you think.

Replace the worked example section with a richer Quick Start that
demonstrates division, multiplication, scaling, and addition — all
using the fluent q() API. Free functions get a one-line mention.
@gdtroszak gdtroszak deleted the branch docs/type-annotations-compound-units February 13, 2026 11:18
@gdtroszak gdtroszak closed this Feb 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation pkg:dim-si dim-si package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants