[wip] drivers: add doxygen for Nordic peripheral drivers

TODO:
      - double check nothing is missing that has a dtcompatible
      - add docstrings for drivers without dtcompatibles
      - add details

Use @zephyrdriver{} and @dtcompatible{} for all Nordic peripheral
device drivers.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

drivers/adc/adc_nrfx_adc.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF51x ADC}
+ * @dtcompatible{nordic,nrf-adc}
+ */
+
 #define ADC_CONTEXT_USES_KERNEL_TIMER
 #include "adc_context.h"
 #include <nrfx_adc.h>

drivers/adc/adc_nrfx_saadc.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF SAADC}
+ * @dtcompatible{nordic,nrf-saadc}
+ */
+
 #define ADC_CONTEXT_USES_KERNEL_TIMER
 #include "adc_context.h"
 #include <hal/nrf_saadc.h>

drivers/clock_control/clock_control_nrf.c

@@ -5,6 +5,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF CLOCK}
+ * @dtcompatible{nordic,nrf-clock}
+ */
+
 #include <soc.h>
 #include <sys/onoff.h>
 #include <drivers/clock_control.h>

drivers/counter/counter_nrfx_rtc.c

@@ -3,6 +3,13 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
+
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF RTC}
+ * @dtcompatible{nordic,nrf-rtc}
+ */
+
 #include <drivers/counter.h>
 #include <drivers/clock_control.h>
 #include <drivers/clock_control/nrf_clock_control.h>

drivers/counter/counter_nrfx_timer.c

@@ -3,6 +3,13 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
+
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF TIMER}
+ * @dtcompatible{nordic,nrf-timer}
+ */
+
 #include <drivers/counter.h>
 #include <hal/nrf_timer.h>
 #include <sys/atomic.h>

drivers/entropy/entropy_nrf5.c

@@ -5,6 +5,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF RNG}
+ * @dtcompatible{nordic,nrf-rng}
+ */
+
 #include <drivers/entropy.h>
 #include <sys/atomic.h>
 #include <soc.h>

drivers/flash/nrf_qspi_nor.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{QSPI NOR on Nordic Semiconductor nRF}
+ * @dtcompatible{nordic,qspi-nor}
+ */
+
 #define DT_DRV_COMPAT nordic_qspi_nor
 
 #include <errno.h>

drivers/flash/soc_flash_nrf.c

@@ -6,6 +6,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF NVMC}
+ * @dtcompatible{nordic,nrf51-flash-controller}
+ * @dtcompatible{nordic,nrf52-flash-controller}
+ * @dtcompatible{nordic,nrf53-flash-controller}
+ * @dtcompatible{nordic,nrf91-flash-controller}
+ */
+
 #include <errno.h>
 
 #include <kernel.h>

drivers/gpio/gpio_nrfx.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF GPIO}
+ * @dtcompatible{nordic,nrf-gpio}
+ */
+
 #include <drivers/gpio.h>
 #include <hal/nrf_gpio.h>
 #include <hal/nrf_gpiote.h>

drivers/hwinfo/hwinfo_nrf.c

@@ -10,6 +10,15 @@
 #include <hal/nrf_ficr.h>
 #include <sys/byteorder.h>
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF SoCs}
+ * @dtcompatible{nordic,nrf-ficr}
+ *
+ * This driver implements HWINFO via the nRF FICR device identifier
+ * registers.
+ */
+
 struct nrf_uid {
 	uint32_t id[2];
 };

drivers/i2c/i2c_nrfx_twi.c

@@ -4,6 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X TWI}
+ * @dtcompatible{nordic,nrf-twi}
+ *
+ * \rst
+ *
+ * To enable this driver, set :option:`CONFIG_I2C`\ ``=y`` via Kconfig,
+ * and make sure you have at least one :dtcompatible:`nordic,nrf-twi` node
+ * in your devicetree with ``status = "okay";`` and other properties
+ * configured as needed.
+ *
+ * \endrst
+ */
 
 #include <drivers/i2c.h>
 #include <dt-bindings/i2c/i2c.h>

drivers/i2c/i2c_nrfx_twim.c

@@ -4,6 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF TWIM}
+ * @dtcompatible{nordic,nrf-twim}
+ *
+ * \rst
+ *
+ * To enable this driver, set :option:`CONFIG_I2C`\ ``=y`` via Kconfig,
+ * and make sure you have at least one :dtcompatible:`nordic,nrf-twim` node
+ * in your devicetree with ``status = "okay";`` and other properties
+ * configured as needed.
+ *
+ * \endrst
+ */
 
 #include <drivers/i2c.h>
 #include <dt-bindings/i2c/i2c.h>

drivers/ipm/ipm_nrfx_ipc.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF IPC}
+ * @dtcompatible{nordic,nrf-ipc}
+ */
+
 #define DT_DRV_COMPAT nordic_nrf_ipc
 
 #include <string.h>

drivers/pwm/Kconfig.nrfx

@@ -11,4 +11,4 @@ config PWM_NRFX
 	select NRFX_PWM2 if "$(dt_nodelabel_enabled,pwm2)"
 	select NRFX_PWM3 if "$(dt_nodelabel_enabled,pwm3)"
 	help
-	  Enable support for nrfx Hardware PWM driver for nRF52 MCU series.
+	  Enable support for nrfx Hardware PWM driver for nRF MCU series.

drivers/pwm/pwm_nrf5_sw.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X GPIOTE based PWM}
+ * @dtcompatible{nordic,nrf-sw-pwm}
+ */
+
 #define DT_DRV_COMPAT nordic_nrf_sw_pwm
 
 #include <soc.h>

drivers/pwm/pwm_nrfx.c

@@ -3,6 +3,13 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
+
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF PWM}
+ * @dtcompatible{nordic,nrf-pwm}
+ */
+
 #include <nrfx_pwm.h>
 #include <drivers/pwm.h>
 #include <hal/nrf_gpio.h>

drivers/sensor/nrf5/temp_nrf5.c

@@ -5,6 +5,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X TEMP}
+ * @dtcompatible{nordic,nrf-temp}
+ */
+
 #define DT_DRV_COMPAT nordic_nrf_temp
 
 #include <device.h>

drivers/sensor/qdec_nrfx/qdec_nrfx.c

@@ -4,6 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X QDEC}
+ * @dtcompatible{nordic,nrf-qdec}
+ *
+ * \rst
+ * This driver implements the ``SENSOR_CHAN_ROTATION`` channel
+ * using the QDEC peripheral.
+ * \endrst
+ */
+
 #include <drivers/sensor.h>
 
 #include <nrfx_qdec.h>

drivers/serial/uart_nrfx_uart.c

@@ -5,7 +5,9 @@
  */
 
 /**
- * @brief Driver for Nordic Semiconductor nRF5X UART
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X UART}
+ * @dtcompatible{nordic,nrf-uart}
  */
 
 #include <drivers/uart.h>

drivers/serial/uart_nrfx_uarte.c

@@ -5,7 +5,9 @@
  */
 
 /**
- * @brief Driver for Nordic Semiconductor nRF UARTE
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF UARTE}
+ * @dtcompatible{nordic,nrf-uarte}
  */
 
 #include <drivers/uart.h>

drivers/spi/spi_nrfx_spi.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X SPI}
+ * @dtcompatible{nordic,nrf-spi}
+ */
+
 #include <drivers/spi.h>
 #include <nrfx_spi.h>
 

drivers/spi/spi_nrfx_spim.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X SPIM}
+ * @dtcompatible{nordic,nrf-spim}
+ */
+
 #include <drivers/spi.h>
 #include <nrfx_spim.h>
 #include <string.h>

drivers/spi/spi_nrfx_spis.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF5X SPIS}
+ * @dtcompatible{nordic,nrf-spis}
+ */
+
 #include <drivers/spi.h>
 #include <nrfx_spis.h>
 

drivers/usb/device/usb_dc_nrfx.c

@@ -6,11 +6,9 @@
  */
 
 /**
- * @file  usb_dc_nrfx.c
- * @brief Nordic USB device controller driver
- *
- * The driver implements the interface between the USBD peripheral
- * driver from nrfx package and the operating system.
+ * @file
+ * @zephyrdriver{Nordic Semiconductor USBD}
+ * @dtcompatible{nordic,nrf-usbd}
  */
 
 #include <soc.h>

drivers/watchdog/wdt_nrfx.c

@@ -4,6 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @zephyrdriver{Nordic Semiconductor nRF WDT}
+ * @dtcompatible{nordic,nrf-watchdog}
+ */
+
 #include <nrfx_wdt.h>
 #include <drivers/watchdog.h>