Merge pull request #7289 from aabadie/can_fix_doc

drivers/can: fix doxygen documentation + typo

cpu/native/can/candev_linux.c

@@ -7,7 +7,7 @@
  */
 
 /**
- * @ingroup     native_cpu
+ * @ingroup     drivers_candev_linux
  * @{
  *
  * @file

cpu/native/include/candev_linux.h

@@ -7,9 +7,9 @@
  */
 
 /**
- * @ingroup     native_cpu
+ * @defgroup    drivers_candev_linux SocketCAN driver
  * @ingroup     drivers_can
- * @defgroup    candev_linux SocketCAN driver
+ * @brief       Implementation of simulated CAN controller driver using SocketCAN on Linux
  * @{
  *
  * @file
@@ -18,7 +18,6 @@
  * @author      Hermann Lelong <[email protected]>
  * @author      Aurelien Gonce <[email protected]>
  * @author      Vincent Dupont <[email protected]>
- * @}
  */
 
 #ifndef CANDEV_LINUX_H
@@ -102,3 +101,4 @@ extern candev_linux_conf_t candev_linux_conf[CAN_DLL_NUMOF];
 #endif
 
 #endif /* CANDEV_LINUX_H */
+/** @} */

cpu/native/include/candev_linux_params.h

@@ -7,14 +7,13 @@
  */
 
 /**
- * @ingroup     candev_linux
+ * @ingroup     drivers_candev_linux
  * @{
  *
  * @file
  * @brief       Default linux can config
  *
  * @author      Vincent Dupont <[email protected]>
- * @}
  */
 
 #ifndef CANDEV_LINUX_PARAMS_H

drivers/can_trx/can_trx.c

@@ -7,16 +7,15 @@
  */
 
 /**
- * @defgroup    drivers_can transceiver
- * @ingroup     drivers
+ * @ingroup     drivers_can_trx
  * @brief       generic transceiver interface
- *
  * @{
  *
  * @file
  * @brief       generic transceiver interface
  *
  * @author      Vincent Dupont <[email protected]>
+ * @}
  */
 
 #include <errno.h>

drivers/include/can/can_trx.h

@@ -7,15 +7,13 @@
  */
 
 /**
- * @defgroup    trx_can CAN transceiver
- * @ingroup     can
- * @ingroup     drivers
- * @brief       generic transceiver interface
- *
+ * @defgroup    drivers_can_trx CAN transceiver interface
+ * @ingroup     drivers_can
+ * @brief       CAN generic transceiver interface
  * @{
  *
  * @file
- * @brief       generic transceiver interface
+ * @brief       CAN generic transceiver interface
  *
  * @author      Aurelien Gonce <[email protected]>
  * @author      Vincent Dupont <[email protected]>

drivers/include/can/candev.h

@@ -7,15 +7,15 @@
  */
 
 /**
- * @ingroup     can
- * @ingroup     drivers
- * @defgroup    drivers_can CAN drivers
+ * @defgroup    drivers_candev CAN device driver interface
+ * @ingroup     drivers_can
+ * @brief       Definitions for low-level CAN driver interface
  * @{
  *
- * This is the CAN controller driver interface
+ * This is the CAN controller generic driver interface
  *
  * @file
- * @brief       Definitions low-level CAN driver interface
+ * @brief       Definitions for low-level CAN driver interface
  *
  * @author      Vincent Dupont <[email protected]>
  * @author      Toon Stegen <[email protected]>
@@ -37,12 +37,12 @@ extern "C" {
 
 
 /**
- * @brief   Possible event types that are send from the device driver to the
+ * @brief   Possible event types that are sent from the device driver to the
  *          upper layer
  */
 typedef enum {
     CANDEV_EVENT_NOEVENT,          /**< no event, used internally */
-    CANDEV_EVENT_ISR,              /**< driver needs it's ISR handled */
+    CANDEV_EVENT_ISR,              /**< driver needs its ISR handled */
     CANDEV_EVENT_WAKE_UP,          /**< driver has been woken up by bus */
     CANDEV_EVENT_TX_CONFIRMATION,  /**< a packet has been sent */
     CANDEV_EVENT_TIMEOUT_TX_CONF,  /**< tx conf timeout received */

drivers/include/can/doc.txt

@@ -0,0 +1,9 @@
+/**
+ * @defgroup    drivers_can CAN Drivers
+ * @ingroup     drivers_netdev
+ * @brief       Drivers for CAN devices
+ * @see         sys_can
+ *
+ * @note        These devices are not covered by the @ref drivers_netdev API
+ *              but by the @ref drivers_candev API.
+ */

sys/can/conn/isotp.c

@@ -7,10 +7,13 @@
  */
 
 /**
+ * @ingroup     sys_can_conn
+ * @{
  * @file
  * @brief       Implementation of isotp CAN connection
  *
  * @author      Vincent Dupont <[email protected]>
+ * @}
  */
 
 #ifdef MODULE_CAN_ISOTP

sys/can/conn/raw.c

@@ -7,10 +7,13 @@
  */
 
 /**
+ * @ingroup     sys_can_conn
+ * @{
  * @file
  * @brief       Implementation of raw CAN connection
  *
  * @author      Vincent Dupont <[email protected]>
+ * @}
  */
 
 #include <errno.h>

sys/can/device.c

@@ -7,12 +7,15 @@
  */
 
 /**
+ * @ingroup     sys_can_dll
+ * @{
  * @file
  * @brief       CAN device interface
  *
  * @author      Toon Stegen <[email protected]>
  * @author      Vincent Dupont <[email protected]>
  * @author      Aurelien Gonce <[email protected]>
+ * @}
  */
 
 #include <errno.h>

sys/can/dll.c

@@ -7,6 +7,8 @@
  */
 
 /**
+ * @ingroup     sys_can_dll
+ * @{
  * @file
  * @brief       CAN Data Link Layer module
  *
@@ -18,6 +20,7 @@
  * @author      Toon Stegen <[email protected]>
  * @author      Vincent Dupont <[email protected]>
  * @author      Aurelien Gonce <[email protected]>
+ * @}
  */
 
 #include <errno.h>

sys/can/isotp/isotp.c

@@ -7,10 +7,13 @@
  */
 
 /**
+ * @ingroup     sys_can_isotp
+ * @{
  * @file
  * @brief       ISO TP high level interface
  *
  * @author      Vincent Dupont <[email protected]>
+ * @}
  */
 
 #include <errno.h>

sys/can/pkt.c

@@ -7,11 +7,14 @@
  */
 
 /**
+ * @ingroup     sys_can_dll
+ * @{
  * @file
  * @brief       CAN memory allocation module
  *
  * @author      Vincent Dupont <[email protected]>
  * @author      Toon Stegen <[email protected]>
+ * @}
  */
 
 #include <string.h>

sys/can/router.c

@@ -7,12 +7,14 @@
  */
 
 /**
- *
+ * @ingroup     sys_can_dll
+ * @{
  * @file
  * @brief       Functions for routing RX can frames
  *
  * @author      Toon Stegen <[email protected]>
  * @author      Vincent Dupont <[email protected]>
+ * @}
  */
 
 #include <stdint.h>

sys/include/can/can.h

@@ -7,16 +7,15 @@
  */
 
 /**
- * @ingroup     can
- * @defgroup    can_dll Data Link Layer
+ * @defgroup    sys_can_dll Data Link Layer
+ * @ingroup     sys_can
  * @brief       CAN Data Link Layer
  *
  * The Data Link Layer is composed of the device, router, pkt and dll files.
- * It can be used to send and receive raw CAN frames through multiple CAN controllers.
- *
+ * It can be used to send and receive raw CAN frames through multiple CAN
+ * controllers.
  * @{
  *
- *
  * @file
  * @brief       Definitions high-level CAN interface
  *

sys/include/can/common.h

@@ -7,8 +7,8 @@
  */
 
 /**
- * @ingroup    can
- * @defgroup   can_common  Common
+ * @defgroup   sys_can_common  Common definitions
+ * @ingroup    sys_can
  * @brief      CAN stack common definitions
  *
  * This module defines the common part of the CAN stack, including structures

sys/include/can/conn/isotp.h

@@ -7,10 +7,9 @@
  */
 
 /**
- * @ingroup    conn_can
+ * @ingroup    sys_can_conn
  * @{
  *
- *
  * @file
  * @brief       Definitions of generic CAN interface
  *

sys/include/can/conn/raw.h

@@ -7,15 +7,14 @@
  */
 
 /**
- * @ingroup     can
- * @defgroup    conn_can Connection
+ * @defgroup    sys_can_conn Connection
+ * @ingroup     sys_can
  * @brief       conn interface for CAN stack
  *
  * This is the user interface to send and receive raw CAN frames or ISO-TP datagrams
  *
  * @{
  *
- *
  * @file
  * @brief       Definitions of generic CAN interface
  *

sys/include/can/device.h

@@ -7,10 +7,9 @@
  */
 
 /**
- * @ingroup    can_dll
+ * @ingroup    sys_can_dll
  * @{
  *
- *
  * @file
  * @brief       Definitions of CAN device interface
  *

sys/include/can/dll.h

@@ -7,10 +7,9 @@
  */
 
 /**
- * @ingroup    can_dll
+ * @ingroup    sys_can_dll
  * @{
  *
- *
  * @file
  * @brief       Definitions of low-level CAN DLL interface
  *

sys/include/can/doc.txt

@@ -1,5 +1,6 @@
 /**
- * @defgroup can CAN
+ * @defgroup sys_can CAN (Controller Area Network)
+ * @ingroup net
  * @brief RIOT CAN stack
  *
  * This module is a full CAN stack integrated to RIOT.
@@ -20,4 +21,6 @@
  *
  * Finally, the connection layer is the user interface to send and receive raw
  * CAN frames or ISO-TP datagrams.
+ *
+ * @see drivers_can
  */

sys/include/can/isotp.h

@@ -7,12 +7,11 @@
  */
 
 /**
- * @ingroup     can
- * @defgroup    isotp ISOTP
+ * @defgroup    sys_can_isotp ISO transport protocol over CAN
+ * @ingroup     sys_can
  * @brief       ISO transport protocol over CAN (ISO15765)
  * @{
  *
- *
  * @file
  * @brief       ISO TP high level interface
  *

sys/include/can/pkt.h

@@ -7,10 +7,9 @@
  */
 
 /**
- * @ingroup    can_dll
+ * @ingroup    sys_can_dll
  * @{
  *
- *
  * @file
  * @brief       CAN memory allocation module
  *
@@ -148,5 +147,4 @@ void can_pkt_buf_free(void *data, size_t size);
 #endif
 
 #endif /* CAN_PKT_H */
-
 /** @} */

sys/include/can/raw.h

@@ -7,14 +7,14 @@
  */
 
 /**
- * @ingroup    can_dll
+ * @ingroup    sys_can_dll
  * @{
  *
- *
  * @file
  * @brief       Definitions high-level RAW CAN interface
  *
- * This file defines the hig-level CAN interface to send and receive RAW CAN frame.
+ * This file defines the high-level CAN interface to send and receive RAW CAN
+ * frame.
  *
  * @author      Vincent Dupont <[email protected]>
  * @author      Toon Stegen <[email protected]>