# `gemath` API conventions
This document is the “style guide” for public API naming and organization in `gemath`.
## Naming: methods vs associated functions
- **Instance methods** operate on `self`:
- Example: `v.refract(normal, eta)`, `v.try_refract(normal, eta)`
- **Associated functions** operate on explicit arguments (no receiver), and use a noun describing the first argument:
- Example: `Vec3::reflect_incident(i, n)`
- Example: `Vec3::refract_incident(i, n, eta)`, `Vec3::try_refract_incident(i, n, eta)`
## Naming: `try_*` for fallible operations
- Use `try_*` to return `Option<T>` (or `Result<T, E>` if/when error details matter).
- Example: `Vec2::try_normalize() -> Option<Vec2>`
- Example: `Mat2::inverse() -> Option<Mat2>`
## Naming: legacy / “gb_math / GL-style” APIs
Some APIs are intentionally close to reference implementations or common math-library names.
- Prefer **one canonical name** for each operation.
- If you keep a legacy/compat name, provide a **thin alias** to the canonical name.
Current examples:
- `refract_gl` / `try_refract_gl` are supported as legacy/compat names.
- `refract_incident` / `try_refract_incident` are the naming-consistent aliases.
## Type aliases
- Prefer explicit aliases for common defaults:
- `Vec2f32 = Vec2<(), ()>`
- Similar patterns for matrices / quats / primitives.
## Angles: prefer `Radians` / `Degrees` types
`gemath` exposes strongly-typed angle wrappers in `gemath::angle`:
- `angle::Radians(f32)`
- `angle::Degrees(f32)`
Policy:
- Public rotation constructors and rotation-related entry points should accept typed angles (`Radians` / `Degrees`).
- If a raw `f32`-angle API exists for compatibility, it should be treated as **legacy**:
- Provide a typed-angle alternative (e.g. `*_radians(...)`, `*_deg(...)`).
- Consider `#[deprecated]` on the raw-`f32` entry point to push users towards typed angles.
## Fallible operations
See `DESIGN_FALLIBLE_OPS.md` for the crate-wide policy on normalization, inversion, and checked operations.