docs: units of measure in every Python docstring (#90)

CHANGELOG.md

@@ -8,6 +8,10 @@ Only recent releases are listed. Older entries are in this file's git history (`
 
 - `update_datafiles()` no longer downloads files that are compiled into the library: the IERS tables and gravity models are `default: false` in the manifest (still pinned and fetchable by name), and the unused `leap-seconds.list` (nothing ever read it — the runtime leap-second table is a compiled-in constant) is removed from the manifest entirely. The only static download left is the JPL ephemeris, alongside the daily EOP / space-weather / solar-cycle refreshes ([#163](https://github.com/ssmichael1/satkit/pull/163))
 
+### Docs
+
+- Every Python docstring (`.pyi` stubs and runtime `__doc__`) states units of measure for dimensioned arguments, returns and attributes (SI: meters, m/s, m/s², radians unless the name ends in `_deg`); `sgp4` outputs explicitly noted as meters / m/s in the TEME frame, not the km / km/s of other SGP4 libraries ([#169](https://github.com/ssmichael1/satkit/pull/169))
+
 ## 0.21.2 - 2026-08-30
 
 ### Changed

python/satkit/frametransform.pyi

@@ -700,7 +700,8 @@ def itrf_to_gcrf_state(
 
     Returns:
         A 2-tuple ``(pos_gcrf, vel_gcrf)`` of numpy arrays with the
-        state expressed in GCRF.
+        state expressed in GCRF: position in meters, velocity in m/s
+        (shape ``(3,)`` each, or ``(N, 3)`` for batched input).
 
     Example:
         ```python
@@ -744,7 +745,8 @@ def gcrf_to_itrf_state(
 
     Returns:
         A 2-tuple ``(pos_itrf, vel_itrf)`` where ``vel_itrf`` is the
-        velocity as observed in ITRF.
+        velocity as observed in ITRF: position in meters, velocity in m/s
+        (shape ``(3,)`` each, or ``(N, 3)`` for batched input).
     """
     ...
 
@@ -760,6 +762,14 @@ def itrf_to_gcrf_state_approx(
     2010 precision is not required. Neglects polar motion, so the
     Earth-rotation sweep ``omega_earth x r`` is evaluated in ITRF directly.
     Accepts scalar or batched inputs like :func:`itrf_to_gcrf_state`.
+
+    Args:
+        pos_itrf: ``(3,)`` or ``(N, 3)`` position vector in ITRF, meters
+        vel_itrf: ``(3,)`` or ``(N, 3)`` velocity vector as observed in ITRF, m/s
+        time: Epoch of the state (length-``N`` array/list for batched input)
+
+    Returns:
+        A 2-tuple ``(pos_gcrf, vel_gcrf)``: position in meters, velocity in m/s
     """
     ...
 
@@ -771,6 +781,15 @@ def gcrf_to_itrf_state_approx(
     """Approximate GCRF → ITRF state transform using the IAU-76/FK5
     reduction. Inverse of :func:`itrf_to_gcrf_state_approx`; accurate to
     ~1 arcsec on position. Accepts scalar or batched inputs.
+
+    Args:
+        pos_gcrf: ``(3,)`` or ``(N, 3)`` position vector in GCRF, meters
+        vel_gcrf: ``(3,)`` or ``(N, 3)`` velocity vector in GCRF, m/s
+        time: Epoch of the state (length-``N`` array/list for batched input)
+
+    Returns:
+        A 2-tuple ``(pos_itrf, vel_itrf)``: position in meters, velocity
+        as observed in ITRF in m/s
     """
     ...
 
@@ -946,7 +965,7 @@ def transform_state(
         vel: 3-element velocity vector [m/s]
 
     Returns:
-        ``(pos, vel)`` in ``to_frame``.
+        ``(pos, vel)`` in ``to_frame``: position in meters, velocity in m/s.
     """
     ...
 
@@ -959,5 +978,15 @@ def transform_state_approx(
 ) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
     """State transform using the IAU-76/FK5 approximate reduction. Same
     supported-pair set as :func:`transform_state`.
+
+    Args:
+        from_frame: Source frame
+        to_frame: Destination frame
+        tm: Epoch
+        pos: 3-element position vector, meters
+        vel: 3-element velocity vector, m/s
+
+    Returns:
+        ``(pos, vel)`` in ``to_frame``: position in meters, velocity in m/s.
     """
     ...

python/satkit/moon.pyi

@@ -14,31 +14,34 @@ from .satkit import TimeScalar, TimeArrayLike, TimeInput
 class moonphase:
     """
     Enum representing moon phases
+
+    Each value covers a range of the moon phase angle (see :func:`phase`),
+    given here in degrees.
     """
 
     NewMoon: ClassVar[moonphase]
-    """New Moon (0 - 22.5)"""
+    """New Moon (phase angle 0 - 22.5 degrees, or 337.5 - 360 degrees)"""
 
     WaxingCrescent: ClassVar[moonphase]
-    """Waxing Crescent (22.5 - 67.5)"""
+    """Waxing Crescent (phase angle 22.5 - 67.5 degrees)"""
 
     FirstQuarter: ClassVar[moonphase]
-    """First Quarter (67.5 - 112.5)"""
+    """First Quarter (phase angle 67.5 - 112.5 degrees)"""
 
     WaxingGibbous: ClassVar[moonphase]
-    """Waxing Gibbous (112.5 - 157.5)"""
+    """Waxing Gibbous (phase angle 112.5 - 157.5 degrees)"""
 
     FullMoon: ClassVar[moonphase]
-    """Full Moon (157.5 - 202.5)"""
+    """Full Moon (phase angle 157.5 - 202.5 degrees)"""
 
     WaningGibbous: ClassVar[moonphase]
-    """Waning Gibbous (202.5 - 247.5)"""
+    """Waning Gibbous (phase angle 202.5 - 247.5 degrees)"""
 
     LastQuarter: ClassVar[moonphase]
-    """Last Quarter (247.5 - 292.5)"""
+    """Last Quarter (phase angle 247.5 - 292.5 degrees)"""
 
     WaningCrescent: ClassVar[moonphase]
-    """Waning Crescent (292.5 - 337.5)"""
+    """Waning Crescent (phase angle 292.5 - 337.5 degrees)"""
 
 @typing.overload
 def pos_gcrf(time: TimeScalar) -> npt.NDArray[np.float64]:
@@ -100,7 +103,7 @@ def illumination(time: TimeScalar) -> float:
         time (satkit.time | datetime.datetime): scalar time at which to compute illumination
 
     Returns:
-        float: fractional illumination of moon at the given time
+        float: fractional illumination of moon at the given time, unitless, range 0.0 to 1.0
 
     Example:
         ```python
@@ -120,7 +123,7 @@ def illumination(time: TimeArrayLike) -> list[float]:
         time (TimeArrayLike): list or numpy array of times at which to compute illumination
 
     Returns:
-        list[float]: fractional illumination of moon at each given time
+        list[float]: fractional illumination of moon at each given time, unitless, range 0.0 to 1.0
     """
     ...