From 501631cb213987675fd836a40a77f2a72eefc856 Mon Sep 17 00:00:00 2001
From: Vincent Dupont <vincent@otakeys.com>
Date: Wed, 1 Mar 2017 12:12:34 +0100
Subject: [PATCH] squash! can stm32: add a driver for STM32 bxCAN peripheral

Fix doxygen documentation
---
 cpu/stm32_common/include/candev_stm32.h       | 27 ++++++++++++-------
 .../include/candev_stm32_params.h             |  4 ++-
 2 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/cpu/stm32_common/include/candev_stm32.h b/cpu/stm32_common/include/candev_stm32.h
index 6669ecffe952..63df4ff7603e 100644
--- a/cpu/stm32_common/include/candev_stm32.h
+++ b/cpu/stm32_common/include/candev_stm32.h
@@ -8,14 +8,18 @@
 
 /**
  * @ingroup     cpu_stm32_common
- * @{
- *
- * @file
+ * @ingroup     drivers_can
+ * @defgroup    candev_stm32 STM32 CAN controller
  * @brief       STM32 CAN controller driver (bxCAN)
  *
  * The STM32Fx microcontroller can have an integrated CAN controller (bxCAN)
  *
- * This driver has been tested *ONLY* with a STM32F2 architecture but should work on others
+ * This driver has been tested with a STM32F0,STM32F2 and STM32F4 MCU
+ * but should work on others
+ * @{
+ *
+ * @file
+ * @brief       bxCAN specific definitions
  *
  * @author      Vincent Dupont <vincent@otakeys.com>
  * @}
@@ -34,7 +38,7 @@ extern "C" {
 #include "mutex.h"
 #include "xtimer.h"
 
-#if defined(CPU_FAM_STM32F1) || defined(CPU_FAM_STM32F2) || defined(CPU_FAM_STM32F4) || DOXYGEN
+#if defined(CPU_FAM_STM32F1) || defined(CPU_FAM_STM32F2) || defined(CPU_FAM_STM32F4) || defined(DOXYGEN)
 /** The maximum number of filters: 28 for dual channel, 14 for single channel */
 #define CAN_STM32_NB_FILTER (28)
 #elif defined(CPU_FAM_STM32F0) || defined(CPU_FAM_STM32F3)
@@ -44,10 +48,12 @@ extern "C" {
 #endif
 
 #ifndef CANDEV_STM32_DEFAULT_BITRATE
+/** Default bitrate */
 #define CANDEV_STM32_DEFAULT_BITRATE 500000
 #endif
 
 #ifndef CANDEV_STM32_DEFAULT_SPT
+/** Default sampling-point */
 #define CANDEV_STM32_DEFAULT_SPT 875
 #endif
 
@@ -56,17 +62,18 @@ extern "C" {
 #elif defined(CPU_FAM_STM32F1) || defined(CPU_FAM_STM32F2) || defined(CPU_FAM_STM32F4)
 #define CANDEV_STM32_CHAN_NUMOF 2
 #else
+/** Number of channels in the device (up to 3) */
 #define CANDEV_STM32_CHAN_NUMOF 1
 #endif
 
-/** This structure holds the configuration of a bxCAN device */
+/** bxCAN device configuration */
 typedef struct candev_stm32_conf {
     CAN_TypeDef *can;         /**< CAN device */
     uint32_t rcc_mask;        /**< RCC mask to enable clock */
     gpio_t rx_pin;            /**< RX pin */
     gpio_t tx_pin;            /**< TX pin */
     gpio_af_t af;             /**< Alternate pin function to use */
-#if CANDEV_STM32_CHAN_NUMOF > 1
+#if CANDEV_STM32_CHAN_NUMOF > 1 || defined(DOXYGEN)
     CAN_TypeDef *can_master;  /**< Master CAN device */
     uint32_t master_rcc_mask; /**< Master device RCC mask */
     /** First filter in the bank. For a master channel it must be 0.
@@ -106,6 +113,7 @@ typedef struct candev_stm32_conf {
 #define CAN_STM32_RX_MAIL_FIFO 12
 #endif
 
+/** bxCAN candev descriptor */
 typedef struct candev_stm32 candev_stm32_t;
 
 /** This structure holds anything related to the receive part */
@@ -135,9 +143,8 @@ struct candev_stm32 {
 /**
  * @brief Initializes a stm32 CAN device @p dev with given @p conf
  *
- * @param dev     the device to initialize
- * @param timing  the initial bittiming to set
- * @param conf    the device configuration
+ * @param[in,out] dev     the device to initialize
+ * @param[in] conf        the device configuration
  *
  * @return 0 on success
  */
diff --git a/cpu/stm32_common/include/candev_stm32_params.h b/cpu/stm32_common/include/candev_stm32_params.h
index 7a52c8d33494..f1b32573665e 100644
--- a/cpu/stm32_common/include/candev_stm32_params.h
+++ b/cpu/stm32_common/include/candev_stm32_params.h
@@ -7,7 +7,7 @@
  */
 
 /**
- * @ingroup     cpu_stm32_common
+ * @ingroup     candev_stm32
  * @{
  *
  * @file
@@ -23,6 +23,7 @@
 #include "can/device.h"
 #include "candev_stm32.h"
 
+/** Default STM32 CAN devices config */
 const static candev_stm32_conf_t candev_stm32_conf[] = {
     {
 #if defined(CPU_FAM_STM32F0)
@@ -103,6 +104,7 @@ const static candev_stm32_conf_t candev_stm32_conf[] = {
 #endif
 };
 
+/** Default STM32 CAN devices parameters */
 const static candev_params_t candev_stm32_params[] = {
     {
         .name = "can_stm32_0",