Nicely format doxygen documentation

src/modules/axisunit.h

@@ -18,47 +18,51 @@ using config::Speed;
 using pulse_gen::pos_t;
 using pulse_gen::steps_t;
 
-/// Specialized axis unit type for compile-time conformability testing. Like config::Unit
-/// this is done ensure unit quantities are not mixed between types, while also providing
-/// convenience methods to convert from physical units to AxisUnits directly at compile
-/// time. AxisUnits are just as efficient as non-checked pos_t and steps_t.
+/// Specialized axis unit type for compile-time conformability testing. Like for
+/// unit::Unit this is done ensure quantities are not mixed between types, while also
+/// providing convenience methods to convert from physical units to AxisUnits directly at
+/// compile time. AxisUnits are just as efficient as the non-checked pulse_gen::pos_t and
+/// pulse_gen::steps_t.
 ///
-/// Each axis unit type is separate for each axis, since the low-level count is not
-/// directly comparable across axes. Quantities are normally defined through the
-/// literal operators. Types and base axes are prefixed with a single letter identifier
-/// for the axis: P=pulley, S=selector, I=idler.
+/// Each axis provides separate types for each quantity, since the low-level count is also
+/// not directly comparable across each (depending on the configuration settings).
+/// Quantities are normally defined through the literal operators. Types and base axes are
+/// prefixed with a single letter identifier for the axis: P=pulley, S=selector, I=idler.
 ///
-///   P_pos_t pulley_position = 10.0_P_mm;
-///   auto pulley_zero = 0.0_P_mm; // implicit type
-///   P_speed_ pulley_feedrate = 30.0_P_mm_s;
-///   I_pos_t idler_position = 15.0_I_deg;
-///   pulley_position + idler_position; // compile time error
+///     P_pos_t pulley_position = 10.0_P_mm;
+///     auto pulley_zero = 0.0_P_mm; // implicit type
+///     P_speed_ pulley_feedrate = 30.0_P_mm_s;
+///     I_pos_t idler_position = 15.0_I_deg;
+///     pulley_position + idler_position; // compile time error
 ///
-/// modules::motion::Motion.PlanMove (and related functions) support both physical and
-/// AxisUnit natively. This is done by specifying the axis through the first template
-/// parameter, which ensures related units are also conforming:
+/// motion::Motion.PlanMove (and related functions) support both physical and AxisUnit
+/// natively. This is done by specifying the axis through the first template parameter,
+/// which ensures related units are also conforming:
 ///
-///   motion.PlanMoveTo<Pulley>(10.0_mm, 100._mm_s); // using physical units
-///   motion.PlanMoveTo<Pulley>(10.0_P_mm, 100._P_mm_s); // using AxisUnit
+///     motion.PlanMoveTo<Pulley>(10.0_mm, 100._mm_s); // using physical units
+///     motion.PlanMoveTo<Pulley>(10.0_P_mm, 100._P_mm_s); // using AxisUnit
 ///
 /// Physical units are always represented with the largest floating point type, so they
-/// should only be used at compile-time (constants, fixed-lenght moves).
+/// should only preferably be used at compile-time only.
 ///
-/// If runtime manipulation is necessary, use AxisUnit should always be used instead.
-/// Conversion from physical to AxisUnit can be done through unitToAxisUnit:
+/// If runtime manipulation is necessary, AxisUnit should be used instead. Conversion from
+/// physical to AxisUnit can be done through motion::unitToAxisUnit:
 ///
-///   unitToAxisUnit<final_type>(physical_type)
+///     unitToAxisUnit<final_type>(physical_type)
 ///
 /// Examples:
 ///
-///   P_pos_t pulley_pos = unitToAxisUnit<P_pos_t>(10.0_mm);
-///   P_speed_t pulley_speed = unitToAxisUnit<P_speed_t>(100.0_mm_s);
+///     P_pos_t pulley_pos = unitToAxisUnit<P_pos_t>(10.0_mm);
+///     P_speed_t pulley_speed = unitToAxisUnit<P_speed_t>(100.0_mm_s);
 ///
-/// Conversion to pos_t or steps_t works the same using unitToSteps instead.
+/// Conversion to pos_t or steps_t works the same using motion::unitToSteps instead.
 ///
 /// The low-level step count can be accessed when necessary through AxisUnit::v, which
-/// should be avoided as it bypasses type checks. AxisUnit can also be constructed by
-/// providing a counter as the first initializer.
+/// should be avoided as it bypasses all type checks. AxisUnit can also be constructed
+/// without checks by providing a counter as the first initializer.
+///
+/// The scaling factor is stored with the pair config::AxisConfig::uSteps and
+/// config::AxisConfig::stepsPerUnit.
 template <typename T, Axis A, config::UnitType U>
 struct AxisUnit {
     T v;
@@ -88,7 +92,9 @@ static constexpr AxisScale axisScale[config::NUM_AXIS] = {
     { config::idlerLimits.base, config::idler.stepsPerUnit },
 };
 
-/// Convert a Unit to AxisUnit
+/// Convert a unit::Unit to AxisUnit.
+/// The scaling factor is stored with the pair config::AxisConfig::uSteps and
+/// config::AxisConfig::stepsPerUnit (one per-axis).
 template <typename T, typename U>
 static constexpr T unitToAxisUnit(U v) {
     static_assert(T::unit == U::unit, "incorrect unit type conversion");
@@ -96,7 +102,8 @@ static constexpr T unitToAxisUnit(U v) {
     return { (typename T::type_t)(v.v * axisScale[T::axis].stepsPerUnit) };
 }
 
-/// Convert an Unit to a steps type (pos_t or steps_t)
+/// Convert an unit::Unit to a steps type (pos_t or steps_t).
+/// Extract the raw step count from an AxisUnit with type checking.
 template <typename AU, typename U>
 static constexpr typename AU::type_t unitToSteps(U v) {
     return unitToAxisUnit<AU>(v).v;

src/unit.h

@@ -7,20 +7,20 @@
 /// daunting, usage is quite straightforward once the appropriate aliases and inline
 /// operators are defined:
 ///
-/// U_mm distance = 10.0_mm;
-/// auto another = 20.5_mm;
-/// auto sum = distance + another;
+///     U_mm distance = 10.0_mm;
+///     auto another = 20.5_mm;
+///     auto sum = distance + another;
 ///
-/// auto angle = 15.0_deg;
-/// auto test = distance + angle; // compile time error
+///     auto angle = 15.0_deg;
+///     auto test = distance + angle; // compile time error
 ///
-/// Template parameters are only used for type checking. The Unit contains a single value
+/// Template parameters are only used for type checking. Unit contains a single value
 /// Unit<T>::v and is thus well suited for parameter passing and inline initialization.
 ///
 /// Conversion to physical steps is done in modules::motion through the sister class
-/// AxisUnit, which also ensures quantities from different axes are not mixed together.
-/// AxisUnit are the normal units that should be used at runtime, which is why physical
-/// units and operators are not exported into the global namespace by default.
+/// modules::motion::AxisUnit, modules::motion::unitToAxisUnit and
+/// modules::motion::unitToSteps, which also ensures quantities from different axes are
+/// not mixed together. AxisUnit are the normal type that *should* be used at runtime.
 namespace unit {
 
 /// Base units for conformability testing