pll: docs refinement

src/pll.rs

@@ -3,8 +3,8 @@ use serde::{Deserialize, Serialize};
 /// Type-II, sampled phase, discrete time PLL
 ///
 /// This PLL tracks the frequency and phase of an input signal with respect to the sampling clock.
-/// The transfer function is I^2,I from input phase to output phase and P,I from input phase to
-/// output frequency.
+/// The open loop transfer function is I^2,I from input phase to output phase and P,I from input
+/// phase to output frequency.
 ///
 /// The transfer functions (for phase and frequency) contain an additional zero at Nyquist.
 ///
@@ -14,8 +14,8 @@ use serde::{Deserialize, Serialize};
 ///
 /// The frequency and phase settling time constants for a frequency/phase jump are `1 << shift`
 /// update cycles. The loop bandwidth is `1/(2*pi*(1 << shift))` in units of the sample rate.
-/// While the phase is being settled within one turn, there is a typically very small frequency
-/// overshoot.
+/// While the phase is being settled after settling the frequency, there is a typically very
+/// small frequency overshoot.
 ///
 /// All math is naturally wrapping 32 bit integer. Phase and frequency are understood modulo that
 /// overflow in the first Nyquist zone. Expressing the IIR equations in other ways (e.g. single
@@ -26,9 +26,10 @@ use serde::{Deserialize, Serialize};
 /// bias is applied. Rounding is "half up". The phase truncation error can be removed very
 /// efficiently by dithering.
 ///
-/// This PLL does not unwrap phase slips accumulated during lock acquisition. This can and should be
-/// implemented elsewhere by unwrapping and scaling the input phase and un-scaling
-/// and wrapping output phase and frequency. This affects dynamic range, gain, and noise accordingly.
+/// This PLL does not unwrap phase slips accumulated during (frequency) lock acquisition.
+/// This can and should be implemented elsewhere by unwrapping and scaling the input phase
+/// and un-scaling and wrapping output phase and frequency. This then affects dynamic range,
+/// gain, and noise accordingly.
 ///
 /// The extension to I^3,I^2,I behavior to track chirps phase-accurately or to i64 data to
 /// increase resolution for extremely narrowband applications is obvious.