drivers: stepper: fix doxygen documentation

reorganize stepper api function sequence

Signed-off-by: Jilay Pandya <jilay.pandya@outlook.com>

include/zephyr/drivers/stepper.h

@@ -36,26 +36,26 @@ extern "C" {
 #define MICRO_STEP_RES_INDEX(res) LOG2(res)
 
 /**
- * @brief Stepper Motor microstep resolution options
+ * @brief Stepper Motor micro-step resolution options
  */
 enum stepper_micro_step_resolution {
 	/** Full step resolution */
 	STEPPER_MICRO_STEP_1 = 1,
-	/** 2 microsteps per full step */
+	/** 2 micro-steps per full step */
 	STEPPER_MICRO_STEP_2 = 2,
-	/** 4 microsteps per full step */
+	/** 4 micro-steps per full step */
 	STEPPER_MICRO_STEP_4 = 4,
-	/** 8 microsteps per full step */
+	/** 8 micro-steps per full step */
 	STEPPER_MICRO_STEP_8 = 8,
-	/** 16 microsteps per full step */
+	/** 16 micro-steps per full step */
 	STEPPER_MICRO_STEP_16 = 16,
-	/** 32 microsteps per full step */
+	/** 32 micro-steps per full step */
 	STEPPER_MICRO_STEP_32 = 32,
-	/** 64 microsteps per full step */
+	/** 64 micro-steps per full step */
 	STEPPER_MICRO_STEP_64 = 64,
-	/** 128 microsteps per full step */
+	/** 128 micro-steps per full step */
 	STEPPER_MICRO_STEP_128 = 128,
-	/** 256 microsteps per full step */
+	/** 256 micro-steps per full step */
 	STEPPER_MICRO_STEP_256 = 256,
 };
 
@@ -98,32 +98,17 @@ enum stepper_event {
 /**
  * @cond INTERNAL_HIDDEN
  *
- * Stepper motor controller driver API definition and system call entry points.
+ * Stepper driver API definition and system call entry points.
  *
  */
 
 /**
- * @brief enable or disable the stepper motor controller.
+ * @brief enable or disable the stepper driver.
  *
  * @see stepper_enable() for details.
  */
 typedef int (*stepper_enable_t)(const struct device *dev, const bool enable);
 
-/**
- * @brief Move the stepper motor relatively by a given number of microsteps.
- *
- * @see stepper_move_by() for details.
- */
-typedef int (*stepper_move_by_t)(const struct device *dev, const int32_t micro_steps);
-
-/**
- * @brief Set the time interval between steps in nanoseconds.
- *
- * @see stepper_set_microstep_interval() for details.
- */
-typedef int (*stepper_set_microstep_interval_t)(const struct device *dev,
-						const uint64_t microstep_interval_ns);
-
 /**
  * @brief Set the micro-step resolution
  *
@@ -154,18 +139,38 @@ typedef int (*stepper_set_reference_position_t)(const struct device *dev, const
 typedef int (*stepper_get_actual_position_t)(const struct device *dev, int32_t *value);
 
 /**
- * @brief Move the stepper motor to an absolute position in microsteps.
+ * @brief Callback function for stepper events
+ */
+typedef void (*stepper_event_callback_t)(const struct device *dev, const enum stepper_event event,
+					 void *user_data);
+
+/**
+ * @brief Set the callback function to be called when a stepper event occurs
  *
- * @see stepper_move_to() for details.
+ * @see stepper_set_event_callback() for details.
  */
-typedef int (*stepper_move_to_t)(const struct device *dev, const int32_t micro_steps);
+typedef int (*stepper_set_event_callback_t)(const struct device *dev,
+					    stepper_event_callback_t callback, void *user_data);
+/**
+ * @brief Set the time interval between steps in nanoseconds.
+ *
+ * @see stepper_set_microstep_interval() for details.
+ */
+typedef int (*stepper_set_microstep_interval_t)(const struct device *dev,
+						const uint64_t microstep_interval_ns);
+/**
+ * @brief Move the stepper relatively by a given number of micro-steps.
+ *
+ * @see stepper_move_by() for details.
+ */
+typedef int (*stepper_move_by_t)(const struct device *dev, const int32_t micro_steps);
 
 /**
- * @brief Is the target position fo the stepper reached
+ * @brief Move the stepper to an absolute position in micro-steps.
  *
- * @see stepper_is_moving() for details.
+ * @see stepper_move_to() for details.
  */
-typedef int (*stepper_is_moving_t)(const struct device *dev, bool *is_moving);
+typedef int (*stepper_move_to_t)(const struct device *dev, const int32_t micro_steps);
 
 /**
  * @brief Run the stepper with a given step interval in a given direction
@@ -175,34 +180,27 @@ typedef int (*stepper_is_moving_t)(const struct device *dev, bool *is_moving);
 typedef int (*stepper_run_t)(const struct device *dev, const enum stepper_direction direction);
 
 /**
- * @brief Callback function for stepper events
- */
-typedef void (*stepper_event_callback_t)(const struct device *dev, const enum stepper_event event,
-					 void *user_data);
-
-/**
- * @brief Set the callback function to be called when a stepper event occurs
+ * @brief Is the target position fo the stepper reached
  *
- * @see stepper_set_event_callback() for details.
+ * @see stepper_is_moving() for details.
  */
-typedef int (*stepper_set_event_callback_t)(const struct device *dev,
-					    stepper_event_callback_t callback, void *user_data);
+typedef int (*stepper_is_moving_t)(const struct device *dev, bool *is_moving);
 
 /**
- * @brief Stepper Motor Controller API
+ * @brief Stepper Driver API
  */
 __subsystem struct stepper_driver_api {
 	stepper_enable_t enable;
-	stepper_move_by_t move_by;
-	stepper_set_microstep_interval_t set_microstep_interval;
 	stepper_set_micro_step_res_t set_micro_step_res;
 	stepper_get_micro_step_res_t get_micro_step_res;
 	stepper_set_reference_position_t set_reference_position;
 	stepper_get_actual_position_t get_actual_position;
+	stepper_set_event_callback_t set_event_callback;
+	stepper_set_microstep_interval_t set_microstep_interval;
+	stepper_move_by_t move_by;
 	stepper_move_to_t move_to;
-	stepper_is_moving_t is_moving;
 	stepper_run_t run;
-	stepper_set_event_callback_t set_event_callback;
+	stepper_is_moving_t is_moving;
 };
 
 /**
@@ -210,10 +208,13 @@ __subsystem struct stepper_driver_api {
  */
 
 /**
- * @brief Enable or disable motor controller
+ * @brief Enable or disable stepper driver
+ *
+ * @details Enabling the driver will energize the coils, however not set the stepper in motion.
+ * Disabling the driver will de-energize the coils.
  *
- * @param dev pointer to the stepper motor controller instance
- * @param enable Input enable or disable motor controller
+ * @param dev pointer to the stepper driver instance
+ * @param enable Input enable or disable stepper driver
  *
  * @retval -EIO Error during Enabling
  * @retval 0 Success
@@ -228,62 +229,10 @@ static inline int z_impl_stepper_enable(const struct device *dev, const bool ena
 }
 
 /**
- * @brief Set the microsteps to be moved from the current position i.e. relative movement
- *
- * @details The motor will move by the given number of microsteps from the current position.
- * This function is non-blocking.
- *
- * @param dev pointer to the stepper motor controller instance
- * @param micro_steps target microsteps to be moved from the current position
- *
- * @retval -ECANCELED If the stepper is disabled
- * @retval -EIO General input / output error
- * @retval	0 Success
- */
-__syscall int stepper_move_by(const struct device *dev, int32_t micro_steps);
-
-static inline int z_impl_stepper_move_by(const struct device *dev, const int32_t micro_steps)
-{
-	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
-
-	return api->move_by(dev, micro_steps);
-}
-
-/**
- * @brief Set the time interval between steps in microseconds
- *
- * @details For controllers such as DRV8825 where you
- * toggle the STEP Pin, the pulse_length would have to be calculated based on this parameter in the
- * driver.
- * @note Setting step interval does not set the motor into motion, a combination of
- * set_microstep_interval and move is required to set the motor into motion.
- *
- * @param dev pointer to the stepper motor controller instance
- * @param microstep_interval_ns time interval between steps in microseconds
- *
- * @retval -EIO General input / output error
- * @retval -EINVAL If the requested step interval is not supported
- * @retval 0 Success
- */
-__syscall int stepper_set_microstep_interval(const struct device *dev,
-					     uint64_t microstep_interval_ns);
-
-static inline int z_impl_stepper_set_microstep_interval(const struct device *dev,
-							const uint64_t microstep_interval_ns)
-{
-	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
-
-	if (api->set_microstep_interval == NULL) {
-		return -ENOSYS;
-	}
-	return api->set_microstep_interval(dev, microstep_interval_ns);
-}
-
-/**
- * @brief Set the microstep resolution in stepper motor controller
+ * @brief Set the micro-step resolution in stepper driver
  *
- * @param dev pointer to the stepper motor controller instance
- * @param resolution microstep resolution
+ * @param dev pointer to the stepper driver instance
+ * @param resolution micro-step resolution
  *
  * @retval -EIO General input / output error
  * @retval -ENOSYS If not implemented by device driver
@@ -305,10 +254,10 @@ static inline int z_impl_stepper_set_micro_step_res(const struct device *dev,
 }
 
 /**
- * @brief Get the microstep resolution in stepper motor controller
+ * @brief Get the micro-step resolution in stepper driver
  *
- * @param dev pointer to the stepper motor controller instance
- * @param resolution microstep resolution
+ * @param dev pointer to the stepper driver instance
+ * @param resolution micro-step resolution
  *
  * @retval -EIO General input / output error
  * @retval -ENOSYS If not implemented by device driver
@@ -331,7 +280,7 @@ static inline int z_impl_stepper_get_micro_step_res(const struct device *dev,
 /**
  * @brief Set the reference position of the stepper
  *
- * @param dev Pointer to the stepper motor controller instance.
+ * @param dev Pointer to the stepper driver instance.
  * @param value The reference position to set in micro-steps.
  *
  * @retval -EIO General input / output error
@@ -354,8 +303,8 @@ static inline int z_impl_stepper_set_reference_position(const struct device *dev
 /**
  * @brief Get the actual a.k.a reference position of the stepper
  *
- * @param dev pointer to the stepper motor controller instance
- * @param value The actual position to get in microsteps
+ * @param dev pointer to the stepper driver instance
+ * @param value The actual position to get in micro-steps
  *
  * @retval -EIO General input / output error
  * @retval -ENOSYS If not implemented by device driver
@@ -374,61 +323,115 @@ static inline int z_impl_stepper_get_actual_position(const struct device *dev, i
 }
 
 /**
- * @brief Set the absolute target position of the stepper
+ * @brief Set the callback function to be called when a stepper event occurs
  *
- * @details The motor will move to the given microsteps position from the reference position.
- * This function is non-blocking.
+ * @param dev pointer to the stepper driver instance
+ * @param callback Callback function to be called when a stepper event occurs
+ * passing NULL will disable the callback
+ * @param user_data User data to be passed to the callback function
+ *
+ * @retval -ENOSYS If not implemented by device driver
+ * @retval 0 Success
+ */
+__syscall int stepper_set_event_callback(const struct device *dev,
+					 stepper_event_callback_t callback, void *user_data);
+
+static inline int z_impl_stepper_set_event_callback(const struct device *dev,
+						    stepper_event_callback_t callback,
+						    void *user_data)
+{
+	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
+
+	if (api->set_event_callback == NULL) {
+		return -ENOSYS;
+	}
+	return api->set_event_callback(dev, callback, user_data);
+}
+
+/**
+ * @brief Set the time interval between steps in nanoseconds
  *
- * @param dev pointer to the stepper motor controller instance
- * @param micro_steps target position to set in microsteps
+ * @note Setting step interval does not set the stepper into motion, a combination of
+ * set_microstep_interval and move is required to set the stepper into motion.
+ *
+ * @param dev pointer to the stepper driver instance
+ * @param microstep_interval_ns time interval between steps in nanoseconds
  *
- * @retval -ECANCELED If the stepper is disabled
  * @retval -EIO General input / output error
+ * @retval -EINVAL If the requested step interval is not supported
  * @retval -ENOSYS If not implemented by device driver
  * @retval 0 Success
  */
-__syscall int stepper_move_to(const struct device *dev, int32_t micro_steps);
+__syscall int stepper_set_microstep_interval(const struct device *dev,
+					     uint64_t microstep_interval_ns);
 
-static inline int z_impl_stepper_move_to(const struct device *dev, const int32_t micro_steps)
+static inline int z_impl_stepper_set_microstep_interval(const struct device *dev,
+							const uint64_t microstep_interval_ns)
 {
 	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
 
-	if (api->move_to == NULL) {
+	if (api->set_microstep_interval == NULL) {
 		return -ENOSYS;
 	}
-	return api->move_to(dev, micro_steps);
+	return api->set_microstep_interval(dev, microstep_interval_ns);
+}
+
+/**
+ * @brief Set the micro-steps to be moved from the current position i.e. relative movement
+ *
+ * @details The stepper will move by the given number of micro-steps from the current position.
+ * This function is non-blocking.
+ *
+ * @param dev pointer to the stepper driver instance
+ * @param micro_steps target micro-steps to be moved from the current position
+ *
+ * @retval -ECANCELED If the stepper is disabled
+ * @retval -EIO General input / output error
+ * @retval 0 Success
+ */
+__syscall int stepper_move_by(const struct device *dev, int32_t micro_steps);
+
+static inline int z_impl_stepper_move_by(const struct device *dev, const int32_t micro_steps)
+{
+	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
+
+	return api->move_by(dev, micro_steps);
 }
 
 /**
- * @brief Check if the stepper motor is currently moving
+ * @brief Set the absolute target position of the stepper
+ *
+ * @details The stepper will move to the given micro-steps position from the reference position.
+ * This function is non-blocking.
  *
- * @param dev pointer to the stepper motor controller instance
- * @param is_moving Pointer to a boolean to store the moving status of the stepper motor
+ * @param dev pointer to the stepper driver instance
+ * @param micro_steps target position to set in micro-steps
  *
+ * @retval -ECANCELED If the stepper is disabled
  * @retval -EIO General input / output error
  * @retval -ENOSYS If not implemented by device driver
  * @retval 0 Success
  */
-__syscall int stepper_is_moving(const struct device *dev, bool *is_moving);
+__syscall int stepper_move_to(const struct device *dev, int32_t micro_steps);
 
-static inline int z_impl_stepper_is_moving(const struct device *dev, bool *is_moving)
+static inline int z_impl_stepper_move_to(const struct device *dev, const int32_t micro_steps)
 {
 	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
 
-	if (api->is_moving == NULL) {
+	if (api->move_to == NULL) {
 		return -ENOSYS;
 	}
-	return api->is_moving(dev, is_moving);
+	return api->move_to(dev, micro_steps);
 }
 
 /**
  * @brief Run the stepper with a given step interval in a given direction
  *
- * @details The motor shall be set into motion and run continuously until
- * stalled or stopped using some other command, for instance, motor_enable(false). This
+ * @details The stepper shall be set into motion and run continuously until
+ * stalled or stopped using some other command, for instance, stepper_enable(false). This
  * function is non-blocking.
  *
- * @param dev pointer to the stepper motor controller instance
+ * @param dev pointer to the stepper driver instance
  * @param direction The direction to set
  *
  * @retval -ECANCELED If the stepper is disabled
@@ -450,29 +453,25 @@ static inline int z_impl_stepper_run(const struct device *dev,
 }
 
 /**
- * @brief Set the callback function to be called when a stepper event occurs
+ * @brief Check if the stepper is currently moving
  *
- * @param dev pointer to the stepper motor controller instance
- * @param callback Callback function to be called when a stepper event occurs
- * passing NULL will disable the callback
- * @param user_data User data to be passed to the callback function
+ * @param dev pointer to the stepper driver instance
+ * @param is_moving Pointer to a boolean to store the moving status of the stepper
  *
+ * @retval -EIO General input / output error
  * @retval -ENOSYS If not implemented by device driver
  * @retval 0 Success
  */
-__syscall int stepper_set_event_callback(const struct device *dev,
-					 stepper_event_callback_t callback, void *user_data);
+__syscall int stepper_is_moving(const struct device *dev, bool *is_moving);
 
-static inline int z_impl_stepper_set_event_callback(const struct device *dev,
-						    stepper_event_callback_t callback,
-						    void *user_data)
+static inline int z_impl_stepper_is_moving(const struct device *dev, bool *is_moving)
 {
 	const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api;
 
-	if (api->set_event_callback == NULL) {
+	if (api->is_moving == NULL) {
 		return -ENOSYS;
 	}
-	return api->set_event_callback(dev, callback, user_data);
+	return api->is_moving(dev, is_moving);
 }
 
 /**