include: drivers: sensor: improve docs for veml6031

complete doxygen docs for this sensor

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

Author: kartben

include/zephyr/drivers/sensor/veml6031.h

@@ -4,76 +4,89 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#ifndef ZEPHYR_INCLUDE_DRIVERS_SENSOR_VEML6031_H_
-#define ZEPHYR_INCLUDE_DRIVERS_SENSOR_VEML6031_H_
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
- * @brief ALS integration time settings in veml6031_it
+ * @file
+ * @brief Header file for extended sensor API of VEML6031 sensor
+ * @ingroup veml6031_interface
  */
-#define VEML6031_IT_COUNT 8
 
-/**
- * @brief Effective photodiode size in enum veml6031_size.
- */
-#define VEML6031_DIV4_COUNT 2
+#ifndef ZEPHYR_INCLUDE_DRIVERS_SENSOR_VEML6031_H_
+#define ZEPHYR_INCLUDE_DRIVERS_SENSOR_VEML6031_H_
 
 /**
- * @brief Gain selections in enum veml6031_gain.
+ * @defgroup veml6031_interface VEML6031
+ * @ingroup sensor_interface_ext
+ * @brief Vishay VEML6031 High Accuracy Ambient Light Sensor
+ * @{
  */
-#define VEML6031_GAIN_COUNT 4
+
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /**
  * @brief VEML6031 integration time options for ambient light measurements.
+ *
+ * Possible values for @ref SENSOR_ATTR_VEML6031_IT custom attribute.
  */
 enum veml6031_it {
-	VEML6031_IT_3_125,
-	VEML6031_IT_6_25,
-	VEML6031_IT_12_5,
-	VEML6031_IT_25,
-	VEML6031_IT_50,
-	VEML6031_IT_100,
-	VEML6031_IT_200,
-	VEML6031_IT_400,
+	VEML6031_IT_3_125, /**< 3.125 ms */
+	VEML6031_IT_6_25,  /**< 6.25 ms */
+	VEML6031_IT_12_5,  /**< 12.5 ms */
+	VEML6031_IT_25,    /**< 25 ms */
+	VEML6031_IT_50,    /**< 50 ms */
+	VEML6031_IT_100,   /**< 100 ms */
+	VEML6031_IT_200,   /**< 200 ms */
+	VEML6031_IT_400,   /**< 400 ms */
+	/** @cond INTERNAL_HIDDEN */
+	VEML6031_IT_COUNT,
+	/** @endcond */
 };
 
 /**
  * @brief VEML6031 size options for ambient light measurements.
+ *
+ * Possible values for @ref SENSOR_ATTR_VEML6031_DIV4 custom attribute.
  */
 enum veml6031_div4 {
-	VEML6031_SIZE_4_4 = 0x00, /* 0b0 */
-	VEML6031_SIZE_1_4 = 0x01, /* 0b1 */
+	VEML6031_SIZE_4_4 = 0x00, /**< 4/4 photodiode size */
+	VEML6031_SIZE_1_4 = 0x01, /**< 1/4 photodiode size */
+	/** @cond INTERNAL_HIDDEN */
+	VEML6031_DIV4_COUNT = 2,
+	/** @endcond */
 };
 
 /**
  * @brief VEML6031 gain options for ambient light measurements.
  */
 enum veml6031_gain {
-	VEML6031_GAIN_1 = 0x00,    /* 0b00 */
-	VEML6031_GAIN_2 = 0x01,    /* 0b01 */
-	VEML6031_GAIN_0_66 = 0x02, /* 0b10 */
-	VEML6031_GAIN_0_5 = 0x03,  /* 0b11 */
+	VEML6031_GAIN_1 = 0x00,    /**< 1x gain */
+	VEML6031_GAIN_2 = 0x01,    /**< 2x gain */
+	VEML6031_GAIN_0_66 = 0x02, /**< 0.66x gain */
+	VEML6031_GAIN_0_5 = 0x03,  /**< 0.5x gain */
+	/** @cond INTERNAL_HIDDEN */
+	VEML6031_GAIN_COUNT = 4,
+	/** @endcond */
 };
 
 /**
  * @brief VEML6031 ALS interrupt persistence protect number options.
+ *
+ * Possible values for @ref SENSOR_ATTR_VEML6031_PERS custom attribute.
  */
 enum veml6031_pers {
-	VEML6031_PERS_1 = 0x00, /* 0b00 */
-	VEML6031_PERS_2 = 0x01, /* 0b01 */
-	VEML6031_PERS_4 = 0x02, /* 0b10 */
-	VEML6031_PERS_8 = 0x03, /* 0b11 */
+	VEML6031_PERS_1 = 0x00, /**< 1 measurement */
+	VEML6031_PERS_2 = 0x01, /**< 2 measurements */
+	VEML6031_PERS_4 = 0x02, /**< 4 measurements */
+	VEML6031_PERS_8 = 0x03, /**< 8 measurements */
 };
 
 /**
- * @brief VEML6031 specific sensor attributes.
+ * @brief Custom sensor attributes for VEML6031 sensor.
  *
  * For high and low threshold window settings (ALS_WH_L, ALS_WH_H, ALS_WL_L and
- * ALS_WL_H) use the generic attributes <tt>SENSOR_ATTR_UPPER_THRESH</tt> and
- * <tt>SENSOR_ATTR_LOWER_THRESH</tt> with 16-bit unsigned integer values. Both
+ * ALS_WL_H) use the generic attributes @ref SENSOR_ATTR_UPPER_THRESH and
+ * @ref SENSOR_ATTR_LOWER_THRESH with 16-bit unsigned integer values. Both
  * threshold settings are in lux and converted by the driver to a value
  * compatible with the sensor. This conversion depends on the current gain,
  * integration time and effective photodiode size settings. So a change in
@@ -82,15 +95,15 @@ enum veml6031_pers {
  * into the sensor update the thresholds -after- a change of gain or
  * integration time.
  *
- * All attributes must be set for the <tt>SENSOR_CHAN_LIGHT</tt> channel.
+ * All attributes must be set for the @ref SENSOR_CHAN_LIGHT channel.
  *
- * When the sensor goes into saturation <tt>-E2BIG</tt> is returned. This
+ * When the sensor goes into saturation @c -E2BIG is returned. This
  * happens when the maximum value <tt>0xFFFF</tt> is returned as raw ALS value.
  * In this case it's up to the user to reduce one or more of the following
  * attributes to come back into the optimal measurement range of the sensor:
- *  <tt>SENSOR_ATTR_VEML6031_GAIN</tt> (gain)
- *  <tt>SENSOR_ATTR_VEML6031_IT</tt> (integration time)
- *  <tt>SENSOR_ATTR_VEML6031_DIV4</tt> (effective photodiode size)
+ * - @ref SENSOR_ATTR_VEML6031_GAIN (gain)
+ * - @ref SENSOR_ATTR_VEML6031_IT (integration time)
+ * - @ref SENSOR_ATTR_VEML6031_DIV4 (effective photodiode size)
  */
 enum sensor_attribute_veml6031 {
 	/**
@@ -120,7 +133,7 @@ enum sensor_attribute_veml6031 {
 };
 
 /**
- * @brief VEML6031 specific sensor channels.
+ * @brief Custom sensor channels for VEML6031 sensor.
  */
 enum sensor_channel_veml6031 {
 	/**
@@ -136,9 +149,9 @@ enum sensor_channel_veml6031 {
 	 * handling.
 	 *
 	 * It cannot be fetched directly. Instead, this channel's value is
-	 * fetched implicitly using <tt>SENSOR_CHAN_LIGHT</tt>. Trying to call
-	 * <tt>sensor_channel_fetch_chan()</tt> with this enumerator as an
-	 * argument will result in a <tt>-ENOTSUP</tt>.
+	 * fetched implicitly using @ref SENSOR_CHAN_LIGHT. Trying to call
+	 * @ref sensor_sample_fetch_chan with this enumerator as an
+	 * argument will result in a @c -ENOTSUP.
 	 */
 	SENSOR_CHAN_VEML6031_ALS_RAW_COUNTS = SENSOR_CHAN_PRIV_START,
 
@@ -147,7 +160,7 @@ enum sensor_channel_veml6031 {
 	 *
 	 * This channel is the raw IR Channel count output of the sensor. About
 	 * fetching the same as for
-	 * <tt>SENSOR_CHAN_VEML6031_ALS_RAW_COUNTS</tt> applies.
+	 * @ref SENSOR_CHAN_VEML6031_ALS_RAW_COUNTS applies.
 	 */
 	SENSOR_CHAN_VEML6031_IR_RAW_COUNTS,
 };
@@ -156,4 +169,8 @@ enum sensor_channel_veml6031 {
 }
 #endif
 
+/**
+ * @}
+ */
+
 #endif /* ZEPHYR_INCLUDE_DRIVERS_SENSOR_VEML6031_H_ */