From 268c6b647e557a90f9045b5a942bfe94fca737d1 Mon Sep 17 00:00:00 2001
From: Alexandre Abadie <alexandre.abadie@inria.fr>
Date: Sun, 2 Jul 2017 18:33:45 +0200
Subject: [PATCH] drivers/can: fix doxygen documentation + typo
---
cpu/native/can/candev_linux.c | 2 +-
cpu/native/include/candev_linux.h | 6 +++---
cpu/native/include/candev_linux_params.h | 3 +--
drivers/can_trx/can_trx.c | 5 ++---
drivers/include/can/can_trx.h | 10 ++++------
drivers/include/can/candev.h | 14 +++++++-------
drivers/include/can/doc.txt | 9 +++++++++
sys/can/conn/isotp.c | 3 +++
sys/can/conn/raw.c | 3 +++
sys/can/device.c | 3 +++
sys/can/dll.c | 3 +++
sys/can/isotp/isotp.c | 3 +++
sys/can/pkt.c | 3 +++
sys/can/router.c | 4 +++-
sys/include/can/can.h | 9 ++++-----
sys/include/can/common.h | 4 ++--
sys/include/can/conn/isotp.h | 3 +--
sys/include/can/conn/raw.h | 5 ++---
sys/include/can/device.h | 3 +--
sys/include/can/dll.h | 3 +--
sys/include/can/doc.txt | 5 ++++-
sys/include/can/isotp.h | 5 ++---
sys/include/can/pkt.h | 4 +---
sys/include/can/raw.h | 6 +++---
sys/include/can/router.h | 4 +---
25 files changed, 70 insertions(+), 52 deletions(-)
create mode 100644 drivers/include/can/doc.txt
diff --git a/cpu/native/can/candev_linux.c b/cpu/native/can/candev_linux.c
index a481c63a0e..1bbf888e58 100644
--- a/cpu/native/can/candev_linux.c
+++ b/cpu/native/can/candev_linux.c
@@ -7,7 +7,7 @@
*/
/**
- * @ingroup native_cpu
+ * @ingroup drivers_candev_linux
* @{
*
* @file
diff --git a/cpu/native/include/candev_linux.h b/cpu/native/include/candev_linux.h
index 54f451b7e9..d231bd98b0 100644
--- a/cpu/native/include/candev_linux.h
+++ b/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 <hermann@otakeys.com>
* @author Aurelien Gonce <aurelien.gonce@altran.com>
* @author Vincent Dupont <vincent@otakeys.com>
- * @}
*/
#ifndef CANDEV_LINUX_H
@@ -102,3 +101,4 @@ extern candev_linux_conf_t candev_linux_conf[CAN_DLL_NUMOF];
#endif
#endif /* CANDEV_LINUX_H */
+/** @} */
diff --git a/cpu/native/include/candev_linux_params.h b/cpu/native/include/candev_linux_params.h
index 68ce965c18..ec121aa1fb 100644
--- a/cpu/native/include/candev_linux_params.h
+++ b/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 <vincent@otakeys.com>
- * @}
*/
#ifndef CANDEV_LINUX_PARAMS_H
diff --git a/drivers/can_trx/can_trx.c b/drivers/can_trx/can_trx.c
index 0f6057fc84..8e81777427 100644
--- a/drivers/can_trx/can_trx.c
+++ b/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 <vincent@otakeys.com>
+ * @}
*/
#include <errno.h>
diff --git a/drivers/include/can/can_trx.h b/drivers/include/can/can_trx.h
index 432b81ca09..c7385c1279 100644
--- a/drivers/include/can/can_trx.h
+++ b/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 <aurelien.gonce@altran.com>
* @author Vincent Dupont <vincent@otakeys.com>
diff --git a/drivers/include/can/candev.h b/drivers/include/can/candev.h
index 5b6b66775c..ca0cea5298 100644
--- a/drivers/include/can/candev.h
+++ b/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 <vincent@otakeys.com>
* @author Toon Stegen <toon.stegen@altran.com>
@@ -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 */
diff --git a/drivers/include/can/doc.txt b/drivers/include/can/doc.txt
new file mode 100644
index 0000000000..f44698c15f
--- /dev/null
+++ b/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.
+ */
diff --git a/sys/can/conn/isotp.c b/sys/can/conn/isotp.c
index 16b7328275..04468d7c50 100644
--- a/sys/can/conn/isotp.c
+++ b/sys/can/conn/isotp.c
@@ -7,10 +7,13 @@
*/
/**
+ * @ingroup sys_can_conn
+ * @{
* @file
* @brief Implementation of isotp CAN connection
*
* @author Vincent Dupont <vincent@otakeys.com>
+ * @}
*/
#ifdef MODULE_CAN_ISOTP
diff --git a/sys/can/conn/raw.c b/sys/can/conn/raw.c
index 6d3678ddca..d35b93fd76 100644
--- a/sys/can/conn/raw.c
+++ b/sys/can/conn/raw.c
@@ -7,10 +7,13 @@
*/
/**
+ * @ingroup sys_can_conn
+ * @{
* @file
* @brief Implementation of raw CAN connection
*
* @author Vincent Dupont <vincent@otakeys.com>
+ * @}
*/
#include <errno.h>
diff --git a/sys/can/device.c b/sys/can/device.c
index ab159aaab7..8d12aa05d8 100644
--- a/sys/can/device.c
+++ b/sys/can/device.c
@@ -7,12 +7,15 @@
*/
/**
+ * @ingroup sys_can_dll
+ * @{
* @file
* @brief CAN device interface
*
* @author Toon Stegen <toon.stegen@altran.com>
* @author Vincent Dupont <vincent@otakeys.com>
* @author Aurelien Gonce <aurelien.gonce@altran.com>
+ * @}
*/
#include <errno.h>
diff --git a/sys/can/dll.c b/sys/can/dll.c
index d3ac0f0967..ea221d65fd 100644
--- a/sys/can/dll.c
+++ b/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 <toon.stegen@altran.com>
* @author Vincent Dupont <vincent@otakeys.com>
* @author Aurelien Gonce <aurelien.gonce@altran.com>
+ * @}
*/
#include <errno.h>
diff --git a/sys/can/isotp/isotp.c b/sys/can/isotp/isotp.c
index 8ee8c72b2d..d3958f8923 100644
--- a/sys/can/isotp/isotp.c
+++ b/sys/can/isotp/isotp.c
@@ -7,10 +7,13 @@
*/
/**
+ * @ingroup sys_can_isotp
+ * @{
* @file
* @brief ISO TP high level interface
*
* @author Vincent Dupont <vincent@otakeys.com>
+ * @}
*/
#include <errno.h>
diff --git a/sys/can/pkt.c b/sys/can/pkt.c
index cf032e81c1..05759e53c1 100644
--- a/sys/can/pkt.c
+++ b/sys/can/pkt.c
@@ -7,11 +7,14 @@
*/
/**
+ * @ingroup sys_can_dll
+ * @{
* @file
* @brief CAN memory allocation module
*
* @author Vincent Dupont <vincent@otakeys.com>
* @author Toon Stegen <toon.stegen@altran.com>
+ * @}
*/
#include <string.h>
diff --git a/sys/can/router.c b/sys/can/router.c
index 2471c33b37..9b0103ca75 100644
--- a/sys/can/router.c
+++ b/sys/can/router.c
@@ -7,12 +7,14 @@
*/
/**
- *
+ * @ingroup sys_can_dll
+ * @{
* @file
* @brief Functions for routing RX can frames
*
* @author Toon Stegen <toon.stegen@altran.com>
* @author Vincent Dupont <vincent@otakeys.com>
+ * @}
*/
#include <stdint.h>
diff --git a/sys/include/can/can.h b/sys/include/can/can.h
index 477aec7ed4..dece74ef60 100644
--- a/sys/include/can/can.h
+++ b/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
*
diff --git a/sys/include/can/common.h b/sys/include/can/common.h
index 38040fadc1..d6104990ed 100644
--- a/sys/include/can/common.h
+++ b/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
diff --git a/sys/include/can/conn/isotp.h b/sys/include/can/conn/isotp.h
index e0139aa3f8..24fbbba5c3 100644
--- a/sys/include/can/conn/isotp.h
+++ b/sys/include/can/conn/isotp.h
@@ -7,10 +7,9 @@
*/
/**
- * @ingroup conn_can
+ * @ingroup sys_can_conn
* @{
*
- *
* @file
* @brief Definitions of generic CAN interface
*
diff --git a/sys/include/can/conn/raw.h b/sys/include/can/conn/raw.h
index fee1fbc066..5a7e03be7f 100644
--- a/sys/include/can/conn/raw.h
+++ b/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
*
diff --git a/sys/include/can/device.h b/sys/include/can/device.h
index ba8c07b780..00c7e2b117 100644
--- a/sys/include/can/device.h
+++ b/sys/include/can/device.h
@@ -7,10 +7,9 @@
*/
/**
- * @ingroup can_dll
+ * @ingroup sys_can_dll
* @{
*
- *
* @file
* @brief Definitions of CAN device interface
*
diff --git a/sys/include/can/dll.h b/sys/include/can/dll.h
index 503e97fb98..7b00dc6041 100644
--- a/sys/include/can/dll.h
+++ b/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
*
diff --git a/sys/include/can/doc.txt b/sys/include/can/doc.txt
index 6b17fecc42..089aa8edf1 100644
--- a/sys/include/can/doc.txt
+++ b/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
*/
diff --git a/sys/include/can/isotp.h b/sys/include/can/isotp.h
index 2fe456385e..a02edfc241 100644
--- a/sys/include/can/isotp.h
+++ b/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
*
diff --git a/sys/include/can/pkt.h b/sys/include/can/pkt.h
index 9744254dda..2cb9c05181 100644
--- a/sys/include/can/pkt.h
+++ b/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 */
-
/** @} */
diff --git a/sys/include/can/raw.h b/sys/include/can/raw.h
index 4420be9d40..b8ef3657e3 100644
--- a/sys/include/can/raw.h
+++ b/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 <vincent@otakeys.com>
* @author Toon Stegen <toon.stegen@altran.com>
diff --git a/sys/include/can/router.h b/sys/include/can/router.h
index d5679a1df8..cf2aeb97fc 100644
--- a/sys/include/can/router.h
+++ b/sys/include/can/router.h
@@ -7,10 +7,9 @@
*/
/**
- * @ingroup can_dll
+ * @ingroup sys_can_dll
* @{
*
- *
* @file
* @brief Functions for routing RX can frames
*
@@ -112,5 +111,4 @@ int can_router_dispatch_tx_error(can_pkt_t *pkt);
#endif
#endif /* CAN_ROUTER_H */
-
/** @} */
--
GitLab