doc: include: migrate a few subsystems to new driver_api Doxygen alias

This illustrates how one can document driver API by migrating a few
subsystems to the new driver_api Doxygen alias.

Signed-off-by: Benjamin Cabé <[email protected]>

include/zephyr/drivers/adc.h

@@ -695,14 +695,15 @@ typedef int (*adc_api_read_async)(const struct device *dev,
 				  struct k_poll_signal *async);
 
 /**
- * @brief ADC driver API
- *
- * This is the mandatory API any ADC driver needs to expose.
+ * @driver_api{ADC}
  */
 __subsystem struct adc_driver_api {
+	/** @copydoc adc_channel_setup */
 	adc_api_channel_setup channel_setup;
+	/** @copydoc adc_read */
 	adc_api_read          read;
-#ifdef CONFIG_ADC_ASYNC
+#ifdef CONFIG_ADC_ASYNC || __DOXYGEN__
+	/** @copydoc adc_read_async */
 	adc_api_read_async    read_async;
 #endif
 	uint16_t ref_internal;	/* mV */
@@ -801,8 +802,7 @@ static inline int adc_read_dt(const struct adc_dt_spec *spec,
 /**
  * @brief Set an asynchronous read request.
  *
- * @note This function is available only if @kconfig{CONFIG_ADC_ASYNC}
- * is selected.
+ * @kconfig_dep{CONFIG_ADC_ASYNC}
  *
  * If invoked from user mode, any sequence struct options for callback must
  * be NULL.

include/zephyr/drivers/bbram.h

@@ -72,12 +72,21 @@ typedef int (*bbram_api_read_t)(const struct device *dev, size_t offset, size_t
 typedef int (*bbram_api_write_t)(const struct device *dev, size_t offset, size_t size,
 			       const uint8_t *data);
 
+/**
+ * @driver_api{BBRAM}
+ */
 __subsystem struct bbram_driver_api {
+	/** @copydoc bbram_check_invalid */
 	bbram_api_check_invalid_t check_invalid;
+	/** @copydoc bbram_check_standby_power */
 	bbram_api_check_standby_power_t check_standby_power;
+	/** @copydoc bbram_check_power */
 	bbram_api_check_power_t check_power;
+	/** @copydoc bbram_get_size */
 	bbram_api_get_size_t get_size;
+	/** @copydoc bbram_read */
 	bbram_api_read_t read;
+	/** @copydoc bbram_write */
 	bbram_api_write_t write;
 };
 

include/zephyr/drivers/gnss.h

@@ -162,15 +162,25 @@ struct gnss_time {
 	uint8_t century_year;
 };
 
-/** GNSS API structure */
+/**
+ * @driver_api{GNSS}
+ */
 __subsystem struct gnss_driver_api {
+	/** @copydoc gnss_set_fix_rate */
 	gnss_set_fix_rate_t set_fix_rate;
+	/** @copydoc gnss_get_fix_rate */
 	gnss_get_fix_rate_t get_fix_rate;
+	/** @copydoc gnss_set_navigation_mode */
 	gnss_set_navigation_mode_t set_navigation_mode;
+	/** @copydoc gnss_get_navigation_mode */
 	gnss_get_navigation_mode_t get_navigation_mode;
+	/** @copydoc gnss_set_enabled_systems */
 	gnss_set_enabled_systems_t set_enabled_systems;
+	/** @copydoc gnss_get_enabled_systems */
 	gnss_get_enabled_systems_t get_enabled_systems;
+	/** @copydoc gnss_get_supported_systems */
 	gnss_get_supported_systems_t get_supported_systems;
+	/** @copydoc gnss_get_latest_timepulse */
 	gnss_get_latest_timepulse_t get_latest_timepulse;
 };
 

include/zephyr/drivers/gpio.h

@@ -789,41 +789,55 @@ enum gpio_int_trig {
 	GPIO_INT_TRIG_WAKE = GPIO_INT_WAKEUP,
 };
 
+/**
+ * @endcond
+ */
+
+ /**
+  * @driver_api{GPIO}
+  */
 __subsystem struct gpio_driver_api {
+	/** @copydoc gpio_pin_configure */
 	int (*pin_configure)(const struct device *port, gpio_pin_t pin,
 			     gpio_flags_t flags);
-#ifdef CONFIG_GPIO_GET_CONFIG
+#ifdef CONFIG_GPIO_GET_CONFIG || __DOXYGEN__
+	/** @copydoc gpio_pin_get_config */
 	int (*pin_get_config)(const struct device *port, gpio_pin_t pin,
 			      gpio_flags_t *flags);
 #endif
+	/** @copydoc gpio_port_get_raw */
 	int (*port_get_raw)(const struct device *port,
 			    gpio_port_value_t *value);
+	/** @copydoc gpio_port_set_masked_raw */
 	int (*port_set_masked_raw)(const struct device *port,
 				   gpio_port_pins_t mask,
 				   gpio_port_value_t value);
+	/** @copydoc gpio_port_set_bits_raw */
 	int (*port_set_bits_raw)(const struct device *port,
 				 gpio_port_pins_t pins);
+	/** @copydoc gpio_port_clear_bits_raw */
 	int (*port_clear_bits_raw)(const struct device *port,
 				   gpio_port_pins_t pins);
+	/** @copydoc gpio_port_toggle_bits */
 	int (*port_toggle_bits)(const struct device *port,
 				gpio_port_pins_t pins);
+	/** @copydoc gpio_pin_interrupt_configure */
 	int (*pin_interrupt_configure)(const struct device *port,
 				       gpio_pin_t pin,
 				       enum gpio_int_mode, enum gpio_int_trig);
+	/** @copydoc gpio_manage_callback */
 	int (*manage_callback)(const struct device *port,
 			       struct gpio_callback *cb,
 			       bool set);
+	/** @copydoc gpio_get_pending_int */
 	uint32_t (*get_pending_int)(const struct device *dev);
-#ifdef CONFIG_GPIO_GET_DIRECTION
+#ifdef CONFIG_GPIO_GET_DIRECTION || __DOXYGEN__
+	/** @copydoc gpio_port_get_direction */
 	int (*port_get_direction)(const struct device *port, gpio_port_pins_t map,
 				  gpio_port_pins_t *inputs, gpio_port_pins_t *outputs);
 #endif /* CONFIG_GPIO_GET_DIRECTION */
 };
 
-/**
- * @endcond
- */
-
 /**
  * @brief Validate that GPIO port is ready.
  *
@@ -1045,6 +1059,8 @@ static inline int gpio_pin_configure_dt(const struct gpio_dt_spec *spec,
  * If @p inputs or @p outputs is NULL, then this function does not get the
  * respective input or output direction information.
  *
+ * @kconfig_dep{CONFIG_GPIO_GET_DIRECTION}
+ *
  * @param port Pointer to the device structure for the driver instance.
  * @param map Bitmap of pin directions to query.
  * @param inputs Pointer to a variable where input directions will be stored.
@@ -1166,6 +1182,8 @@ static inline int gpio_pin_is_output_dt(const struct gpio_dt_spec *spec)
 /**
  * @brief Get a configuration of a single pin.
  *
+ * @kconfig_dep{CONFIG_GPIO_GET_CONFIG}
+ *
  * @param port Pointer to device structure for the driver instance.
  * @param pin Pin number which configuration is get.
  * @param flags Pointer to variable in which the current configuration will