From 051bce90980da035b4649b7caef29c4d9f0608e0 Mon Sep 17 00:00:00 2001 From: Yuri D'Elia Date: Sun, 25 Jul 2021 23:40:04 +0200 Subject: [PATCH] Nicely format doxygen documentation --- src/modules/axisunit.h | 65 +++++++++++++++++++++++------------------- src/unit.h | 18 ++++++------ 2 files changed, 45 insertions(+), 38 deletions(-) diff --git a/src/modules/axisunit.h b/src/modules/axisunit.h index 736a6fc..5a08fde 100644 --- a/src/modules/axisunit.h +++ b/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(10.0_mm, 100._mm_s); // using physical units -/// motion.PlanMoveTo(10.0_P_mm, 100._P_mm_s); // using AxisUnit +/// motion.PlanMoveTo(10.0_mm, 100._mm_s); // using physical units +/// motion.PlanMoveTo(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(physical_type) +/// unitToAxisUnit(physical_type) /// /// Examples: /// -/// P_pos_t pulley_pos = unitToAxisUnit(10.0_mm); -/// P_speed_t pulley_speed = unitToAxisUnit(100.0_mm_s); +/// P_pos_t pulley_pos = unitToAxisUnit(10.0_mm); +/// P_speed_t pulley_speed = unitToAxisUnit(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 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 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 static constexpr typename AU::type_t unitToSteps(U v) { return unitToAxisUnit(v).v; diff --git a/src/unit.h b/src/unit.h index 52525fb..9364d08 100644 --- a/src/unit.h +++ b/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::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