[riot-notifications] [RIOT-OS/RIOT] dist/tools/doccheck: add exclude file for warnings and use it (#16779)

Martine Lenders notifications at github.com
Tue Aug 31 16:42:22 CEST 2021


> i am not sure how much it can be improved with an documentation comment above each line

Does not need to be above the line. E.g.

```
/**
 * @name USB HID protocol types
 * @{
 */
#define USB_HID_PROTOCOL_NONE       0x0  /** < None */
#define USB_HID_PROTOCOL_KEYBOARD   0x1  /**< Keyboard */
#define USB_HID_PROTOCOL_MOUSE      0x2  /**< Mouse */
/** @} */
```

would also works. But that is exactly the non-sensical doc we don't want, and why we used grouping here in the first place. However, outright masking Group member documentation does not cut it. With that any missing module-part documentation will also pass the test. Take the following patch for example. With your patch that missing documentation would fall through.

```diff
diff --git a/sys/include/net/gnrc/ipv6.h b/sys/include/net/gnrc/ipv6.h
index 7b7ac466ac..5a3f330711 100644
--- a/sys/include/net/gnrc/ipv6.h
+++ b/sys/include/net/gnrc/ipv6.h
@@ -121,28 +121,14 @@ extern "C" {
  * @ingroup     net_gnrc_conf
  * @{
  */
-/**
- * @brief   Default stack size to use for the IPv6 thread
- */
 #ifndef GNRC_IPV6_STACK_SIZE
 #define GNRC_IPV6_STACK_SIZE        (THREAD_STACKSIZE_DEFAULT)
 #endif
 
-/**
- * @brief   Default priority for the IPv6 thread
- */
 #ifndef GNRC_IPV6_PRIO
 #define GNRC_IPV6_PRIO              (THREAD_PRIORITY_MAIN - 3)
 #endif
 
-/**
- * @brief   Default message queue size to use for the IPv6 thread (as exponent
- *          of 2^n).
- *
- *          As the queue size ALWAYS needs to be power of two, this option
- *          represents the exponent of 2^n, which will be used as the size of
- *          the queue.
- */
 #ifndef CONFIG_GNRC_IPV6_MSG_QUEUE_SIZE_EXP
 #define CONFIG_GNRC_IPV6_MSG_QUEUE_SIZE_EXP    (3U)
 #endif
@@ -205,14 +191,6 @@ extern kernel_pid_t gnrc_ipv6_pid;
 extern fib_table_t gnrc_ipv6_fib_table;
 #endif
 
-/**
- * @brief   Initialization of the IPv6 thread.
- *
- * @return  The PID to the IPv6 thread, on success.
- * @return  a negative errno on error.
- * @return  -EOVERFLOW, if there are too many threads running already
- * @return  -EEXIST, if IPv6 was already initialized.
- */
 kernel_pid_t gnrc_ipv6_init(void);
 
 /**
```

```
Running "./dist/tools/doccheck/check.sh" x
Command output:

	ERROR: Doxygen generates the following warnings:
	sys/include/net/gnrc/ipv6.h:125: warning: Member GNRC_IPV6_STACK_SIZE (macro definition) of group net_gnrc_ipv6_conf is not documented.
	sys/include/net/gnrc/ipv6.h:129: warning: Member GNRC_IPV6_PRIO (macro definition) of group net_gnrc_ipv6_conf is not documented.
	sys/include/net/gnrc/ipv6.h:133: warning: Member CONFIG_GNRC_IPV6_MSG_QUEUE_SIZE_EXP (macro definition) of group net_gnrc_ipv6_conf is not documented.
	sys/include/net/gnrc/ipv6.h:194: warning: Member gnrc_ipv6_init(void) (function) of group net_gnrc_ipv6 is not documented.
	sys/include/net/gnrc/ipv6.h:125: warning: Member GNRC_IPV6_STACK_SIZE (macro definition) of group net_gnrc_ipv6_conf is not documented.
	sys/include/net/gnrc/ipv6.h:129: warning: Member GNRC_IPV6_PRIO (macro definition) of group net_gnrc_ipv6_conf is not documented.
	sys/include/net/gnrc/ipv6.h:133: warning: Member CONFIG_GNRC_IPV6_MSG_QUEUE_SIZE_EXP (macro definition) of group net_gnrc_ipv6_conf is not documented.
	sys/include/net/gnrc/ipv6.h:194: warning: Member gnrc_ipv6_init(void) (function) of group net_gnrc_ipv6 is not documented.
	sys/include/net/gnrc/ipv6.h:166: warning: unable to resolve reference to 'gnrc_ipv6_init()' for \ref command
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/16779#issuecomment-909302386
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20210831/8d14ec9e/attachment-0001.htm>


More information about the notifications mailing list