pbio: Avoid direct docstring in header.

In editors like vscode, docstrings in the headers take priority over those in the source, so we should add a line break after the category descriptors.

Otherwise, the hover menu will pick the wrong docstring.

Author: laurensvalk

lib/pbio/include/pbio/angle.h

@@ -28,20 +28,24 @@ typedef struct _pbio_angle_t {
     int32_t millidegrees; /**< Millidegrees.*/
 } pbio_angle_t;
 
-// Conversion to and from basic types.
+// Conversion to and from basic types:
+
 int32_t pbio_angle_to_low_res(pbio_angle_t *a, int32_t scale);
 void pbio_angle_from_low_res(pbio_angle_t *a, int32_t input, int32_t scale);
 
-// Inplace operations on an angle.
+// Inplace operations on an angle:
+
 void pbio_angle_neg(pbio_angle_t *a);
 void pbio_angle_add_mdeg(pbio_angle_t *a, int32_t increment);
 
-// Binary operations on two angles to produce new angle.
+// Binary operations on two angles to produce new angle:
+
 void pbio_angle_diff(pbio_angle_t *a, pbio_angle_t *b, pbio_angle_t *result);
 void pbio_angle_sum(pbio_angle_t *a, pbio_angle_t *b, pbio_angle_t *result);
 void pbio_angle_avg(pbio_angle_t *a, pbio_angle_t *b, pbio_angle_t *result);
 
-// Compares two angles.
+// Compare two angles:
+
 int32_t pbio_angle_diff_mdeg(pbio_angle_t *a, pbio_angle_t *b);
 bool pbio_angle_diff_is_small(pbio_angle_t *a, pbio_angle_t *b);
 

lib/pbio/include/pbio/control.h

@@ -137,25 +137,29 @@ typedef struct _pbio_control_t {
     bool on_target;
 } pbio_control_t;
 
-// Time functions.
+// Time functions:
+
 uint32_t pbio_control_get_time_ticks(void);
 uint32_t pbio_control_get_ref_time(pbio_control_t *ctl, uint32_t time_now);
 bool pbio_control_time_is_later(uint32_t sample, uint32_t base);
 
-// Control loop functions.
+// Control loop functions:
+
 void pbio_control_reset(pbio_control_t *ctl);
 void pbio_control_stop(pbio_control_t *ctl);
 void pbio_control_update(pbio_control_t *ctl, uint32_t time_now, pbio_control_state_t *state, pbio_trajectory_reference_t *ref, pbio_dcmotor_actuation_t *actuation, int32_t *control);
 
-// Control status checks.
+// Control status checks:
+
 bool pbio_control_is_active(pbio_control_t *ctl);
 bool pbio_control_type_is_position(pbio_control_t *ctl);
 bool pbio_control_type_is_time(pbio_control_t *ctl);
 bool pbio_control_is_stalled(pbio_control_t *ctl, uint32_t *stall_duration);
 bool pbio_control_is_done(pbio_control_t *ctl);
 int32_t pbio_control_get_load(pbio_control_t *ctl);
 
-// Start new control command.
+// Start new control command:
+
 pbio_error_t pbio_control_start_position_control(pbio_control_t *ctl, uint32_t time_now, pbio_control_state_t *state, int32_t position, int32_t speed, pbio_control_on_completion_t on_completion);
 pbio_error_t pbio_control_start_position_control_relative(pbio_control_t *ctl, uint32_t time_now, pbio_control_state_t *state, int32_t distance, int32_t speed, pbio_control_on_completion_t on_completion);
 pbio_error_t pbio_control_start_position_control_hold(pbio_control_t *ctl, uint32_t time_now, int32_t position);

lib/pbio/include/pbio/control_settings.h

@@ -111,20 +111,23 @@ typedef struct _pbio_control_settings_t {
  */
 #define pbio_control_time_ticks_to_ms(ticks) ((ticks) / 10)
 
-// Unit conversion functions.
+// Unit conversion functions:
+
 int32_t pbio_control_settings_ctl_to_app(pbio_control_settings_t *s, int32_t input);
 int32_t pbio_control_settings_ctl_to_app_long(pbio_control_settings_t *s, pbio_angle_t *input);
 int32_t pbio_control_settings_app_to_ctl(pbio_control_settings_t *s, int32_t input);
 void pbio_control_settings_app_to_ctl_long(pbio_control_settings_t *s, int32_t input, pbio_angle_t *output);
 int32_t pbio_control_settings_actuation_ctl_to_app(int32_t input);
 int32_t pbio_control_settings_actuation_app_to_ctl(int32_t input);
 
-// Scale values by given constants.
+// Scale values by given constants:
+
 int32_t pbio_control_settings_mul_by_loop_time(int32_t input);
 int32_t pbio_control_settings_mul_by_gain(int32_t value, int32_t gain);
 int32_t pbio_control_settings_div_by_gain(int32_t value, int32_t gain);
 
-// Control settings getters and setters.
+// Control settings getters and setters:
+
 void pbio_control_settings_get_limits(pbio_control_settings_t *s, int32_t *speed, int32_t *acceleration, int32_t *deceleration, int32_t *actuation);
 pbio_error_t pbio_control_settings_set_limits(pbio_control_settings_t *s, int32_t speed, int32_t acceleration, int32_t deceleration, int32_t actuation);
 void pbio_control_settings_get_pid(pbio_control_settings_t *s, int32_t *pid_kp, int32_t *pid_ki, int32_t *pid_kd, int32_t *integral_change_max);

lib/pbio/include/pbio/dcmotor.h

@@ -43,24 +43,29 @@ typedef struct _pbio_dcmotor_t {
 
 #if PBIO_CONFIG_DCMOTOR
 
-// Global reset
+// Global reset:
+
 void pbio_dcmotor_stop_all(bool clear_parents);
 
-// Setup and status
+// Setup and status:
+
 pbio_error_t pbio_dcmotor_get_dcmotor(pbio_port_id_t port, pbio_dcmotor_t **dcmotor);
 pbio_error_t pbio_dcmotor_setup(pbio_dcmotor_t *dcmotor, pbio_direction_t direction);
 void pbio_dcmotor_get_state(pbio_dcmotor_t *dcmotor, pbio_dcmotor_actuation_t *actuation, int32_t *voltage_now);
 
-// Settings
+// Settings:
+
 int32_t pbio_dcmotor_get_max_voltage(pbio_iodev_type_id_t id);
 pbio_error_t pbio_dcmotor_set_settings(pbio_dcmotor_t *dcmotor, int32_t max_voltage);
 void pbio_dcmotor_get_settings(pbio_dcmotor_t *dcmotor, int32_t *max_voltage);
 
-// Actuation for system purposes
+// Actuation for system purposes:
+
 pbio_error_t pbio_dcmotor_coast(pbio_dcmotor_t *dcmotor);
 pbio_error_t pbio_dcmotor_set_voltage(pbio_dcmotor_t *dcmotor, int32_t voltage);
 
-// Actuation for end users
+// Actuation for end users:
+
 pbio_error_t pbio_dcmotor_user_command(pbio_dcmotor_t *dcmotor, bool coast, int32_t voltage);
 
 #else

lib/pbio/include/pbio/drivebase.h

@@ -24,43 +24,37 @@ typedef struct _pbio_drivebase_t {
 
 pbio_error_t pbio_drivebase_get_drivebase(pbio_drivebase_t **db_address, pbio_servo_t *left, pbio_servo_t *right, int32_t wheel_diameter, int32_t axle_track);
 
+// Drive base status:
+
 void pbio_drivebase_update_all(void);
 bool pbio_drivebase_update_loop_is_running(pbio_drivebase_t *db);
+bool pbio_drivebase_is_busy(pbio_drivebase_t *db);
 
-// Finite point to point control
+// Finite point to point control:
 
 pbio_error_t pbio_drivebase_drive_straight(pbio_drivebase_t *db, int32_t distance, pbio_control_on_completion_t on_completion);
-
 pbio_error_t pbio_drivebase_drive_curve(pbio_drivebase_t *db, int32_t radius, int32_t angle, pbio_control_on_completion_t on_completion);
 
-// Infinite driving
+// Infinite driving:
 
 pbio_error_t pbio_drivebase_drive_forever(pbio_drivebase_t *db, int32_t speed, int32_t turn_rate);
-
 pbio_error_t pbio_drivebase_stop(pbio_drivebase_t *db, pbio_control_on_completion_t on_completion);
 
-bool pbio_drivebase_is_busy(pbio_drivebase_t *db);
 
-// Measuring and settings
+// Measuring and settings:
 
 pbio_error_t pbio_drivebase_get_state_user(pbio_drivebase_t *db, int32_t *distance, int32_t *drive_speed, int32_t *angle, int32_t *turn_rate);
-
 pbio_error_t pbio_drivebase_get_drive_settings(pbio_drivebase_t *db, int32_t *drive_speed, int32_t *drive_acceleration, int32_t *drive_deceleration, int32_t *turn_rate, int32_t *turn_acceleration, int32_t *turn_deceleration);
-
 pbio_error_t pbio_drivebase_set_drive_settings(pbio_drivebase_t *db, int32_t drive_speed, int32_t drive_acceleration, int32_t drive_deceleration, int32_t turn_rate, int32_t turn_acceleration, int32_t turn_deceleration);
 
 #if PBIO_CONFIG_DRIVEBASE_SPIKE
 
-// SPIKE drive base wrappers
+// SPIKE drive base wrappers:
 
 pbio_error_t pbio_drivebase_get_drivebase_spike(pbio_drivebase_t **db_address, pbio_servo_t *left, pbio_servo_t *right);
-
 pbio_error_t pbio_drivebase_spike_drive_forever(pbio_drivebase_t *db, int32_t speed_left, int32_t speed_right);
-
 pbio_error_t pbio_drivebase_spike_drive_time(pbio_drivebase_t *db, int32_t speed_left, int32_t speed_right, int32_t duration, pbio_control_on_completion_t on_completion);
-
 pbio_error_t pbio_drivebase_spike_drive_angle(pbio_drivebase_t *db, int32_t speed_left, int32_t speed_right, int32_t angle, pbio_control_on_completion_t on_completion);
-
 pbio_error_t pbio_drivebase_spike_steering_to_tank(int32_t speed, int32_t steering, int32_t *speed_left, int32_t *speed_right);
 
 #endif // PBIO_CONFIG_DRIVEBASE_SPIKE

lib/pbio/include/pbio/integrator.h

@@ -24,14 +24,12 @@ typedef struct _pbio_speed_integrator_t {
     pbio_control_settings_t *settings; // Control settings, which includes integrator settings.
 } pbio_speed_integrator_t;
 
-void pbio_speed_integrator_pause(pbio_speed_integrator_t *itg, uint32_t time_now, int32_t position_error);
+// Speed integrator functions:
 
+void pbio_speed_integrator_pause(pbio_speed_integrator_t *itg, uint32_t time_now, int32_t position_error);
 void pbio_speed_integrator_resume(pbio_speed_integrator_t *itg, int32_t position_error);
-
 void pbio_speed_integrator_reset(pbio_speed_integrator_t *itg, pbio_control_settings_t *settings);
-
 int32_t pbio_speed_integrator_get_error(pbio_speed_integrator_t *itg, int32_t position_error);
-
 bool pbio_speed_integrator_stalled(pbio_speed_integrator_t *itg, uint32_t time_now, int32_t speed_now, int32_t speed_ref);
 
 typedef struct _pbio_position_integrator_t {
@@ -44,16 +42,13 @@ typedef struct _pbio_position_integrator_t {
     pbio_control_settings_t *settings; // Control settings, which includes integrator settings.
 } pbio_position_integrator_t;
 
-uint32_t pbio_position_integrator_get_ref_time(pbio_position_integrator_t *itg, uint32_t time_now);
+// Position integrator functions:
 
+uint32_t pbio_position_integrator_get_ref_time(pbio_position_integrator_t *itg, uint32_t time_now);
 void pbio_position_integrator_pause(pbio_position_integrator_t *itg, uint32_t time_now);
-
 void pbio_position_integrator_resume(pbio_position_integrator_t *itg, uint32_t time_now);
-
 void pbio_position_integrator_reset(pbio_position_integrator_t *itg, pbio_control_settings_t *settings, uint32_t time_now);
-
 int32_t pbio_position_integrator_update(pbio_position_integrator_t *itg, int32_t position_error, int32_t position_remaining);
-
 bool pbio_position_integrator_stalled(pbio_position_integrator_t *itg, uint32_t time_now, int32_t speed_now, int32_t speed_ref);
 
 #endif // _PBIO_INTEGRATOR_H_

lib/pbio/include/pbio/math.h

@@ -14,15 +14,23 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-bool pbio_math_sign_not_opposite(int32_t a, int32_t b);
-int32_t pbio_math_abs(int32_t value);
-int32_t pbio_math_atan2(int32_t y, int32_t x);
+// Clamping and binding:
+
 int32_t pbio_math_bind(int32_t value, int32_t min, int32_t max);
 int32_t pbio_math_clamp(int32_t value, int32_t abs_max);
 int32_t pbio_math_max(int32_t a, int32_t b);
 int32_t pbio_math_min(int32_t a, int32_t b);
-int32_t pbio_math_mult_then_div(int32_t a, int32_t b, int32_t c);
+
+// Signing:
+
+bool pbio_math_sign_not_opposite(int32_t a, int32_t b);
+int32_t pbio_math_abs(int32_t value);
 int32_t pbio_math_sign(int32_t a);
+
+// Integer re-implementations of selected math functions.
+
+int32_t pbio_math_atan2(int32_t y, int32_t x);
+int32_t pbio_math_mult_then_div(int32_t a, int32_t b, int32_t c);
 int32_t pbio_math_sqrt(int32_t n);
 
 #endif // _PBIO_MATH_H_

lib/pbio/include/pbio/observer.h

@@ -78,18 +78,17 @@ typedef struct _pbio_observer_t {
     pbio_control_settings_t *settings;
 } pbio_observer_t;
 
-void pbio_observer_reset(pbio_observer_t *obs, pbio_control_settings_t *settings, pbio_angle_t *angle);
+// Observer state functions:
 
+void pbio_observer_reset(pbio_observer_t *obs, pbio_control_settings_t *settings, pbio_angle_t *angle);
 void pbio_observer_get_estimated_state(pbio_observer_t *obs, pbio_angle_t *angle, int32_t *speed);
-
 void pbio_observer_update(pbio_observer_t *obs, uint32_t time, pbio_angle_t *angle, pbio_dcmotor_actuation_t actuation, int32_t voltage);
-
 bool pbio_observer_is_stalled(pbio_observer_t *obs, uint32_t time, uint32_t *stall_duration);
 
-int32_t pbio_observer_get_feedforward_torque(const pbio_observer_model_t *model, int32_t rate_ref, int32_t acceleration_ref);
+// Model conversion functions:
 
+int32_t pbio_observer_get_feedforward_torque(const pbio_observer_model_t *model, int32_t rate_ref, int32_t acceleration_ref);
 int32_t pbio_observer_torque_to_voltage(const pbio_observer_model_t *model, int32_t desired_torque);
-
 int32_t pbio_observer_voltage_to_torque(const pbio_observer_model_t *model, int32_t voltage);
 
 #endif // _PBIO_OBSERVER_H_

lib/pbio/include/pbio/servo.h

@@ -78,20 +78,23 @@ typedef struct _pbio_servo_t {
     bool run_update_loop;
 } pbio_servo_t;
 
-// Servo initialization and updates.
+// Servo initialization and updates:
+
 pbio_error_t pbio_servo_get_servo(pbio_port_id_t port, pbio_servo_t **srv);
 pbio_error_t pbio_servo_setup(pbio_servo_t *srv, pbio_direction_t direction, int32_t gear_ratio, bool reset_angle);
 pbio_error_t pbio_servo_actuate(pbio_servo_t *srv, pbio_dcmotor_actuation_t actuation_type, int32_t payload);
 pbio_error_t pbio_servo_load_settings(pbio_control_settings_t *control_settings, const pbio_observer_model_t **model, pbio_iodev_type_id_t id);
 void pbio_servo_update_all(void);
 
-// Servo status.
+// Servo status:
+
 pbio_error_t pbio_servo_get_state_control(pbio_servo_t *srv, pbio_control_state_t *state);
 pbio_error_t pbio_servo_get_state_user(pbio_servo_t *srv, int32_t *angle, int32_t *speed);
 bool pbio_servo_update_loop_is_running(pbio_servo_t *srv);
 pbio_error_t pbio_servo_is_stalled(pbio_servo_t *srv, bool *stalled, uint32_t *stall_duration);
 
-// Servo end user commands.
+// Servo end user commands:
+
 pbio_error_t pbio_servo_stop(pbio_servo_t *srv, pbio_control_on_completion_t on_completion);
 pbio_error_t pbio_servo_reset_angle(pbio_servo_t *srv, int32_t reset_angle, bool reset_to_abs);
 pbio_error_t pbio_servo_run_forever(pbio_servo_t *srv, int32_t speed);

lib/pbio/include/pbio/trajectory.h

@@ -75,24 +75,18 @@ typedef struct _pbio_trajectory_t {
     int32_t a2;                          /**<  Encoder acceleration during out-phase */
 } pbio_trajectory_t;
 
-// Make a new full trajectory from user command, with angle target as endpoint.
-pbio_error_t pbio_trajectory_new_angle_command(pbio_trajectory_t *trj, const pbio_trajectory_command_t *command);
+// Make or modify trajectories:
 
-// Make a new full trajectory from user command, with time based endpoint.
+pbio_error_t pbio_trajectory_new_angle_command(pbio_trajectory_t *trj, const pbio_trajectory_command_t *command);
 pbio_error_t pbio_trajectory_new_time_command(pbio_trajectory_t *trj, const pbio_trajectory_command_t *command);
-
-void pbio_trajectory_get_last_vertex(pbio_trajectory_t *trj, uint32_t time_ref, pbio_trajectory_reference_t *ref);
-
-// Make a stationary trajectory for holding position.
 void pbio_trajectory_make_constant(pbio_trajectory_t *trj, const pbio_trajectory_command_t *command);
-
-// Stretches out a given trajectory time-wise to make it match time frames of leading trajectory
 void pbio_trajectory_stretch(pbio_trajectory_t *trj, pbio_trajectory_t *leader);
 
-uint32_t pbio_trajectory_get_duration(pbio_trajectory_t *trj);
+// Reference getter functions:
 
+uint32_t pbio_trajectory_get_duration(pbio_trajectory_t *trj);
 void pbio_trajectory_get_endpoint(pbio_trajectory_t *trj, pbio_trajectory_reference_t *end);
-
+void pbio_trajectory_get_last_vertex(pbio_trajectory_t *trj, uint32_t time_ref, pbio_trajectory_reference_t *ref);
 void pbio_trajectory_get_reference(pbio_trajectory_t *trj, uint32_t time_ref, pbio_trajectory_reference_t *ref);
 
 #endif // _PBIO_TRAJECTORY_H_