From da03ee80d8ba9a22a66b05c68b945ef0301df8c5 Mon Sep 17 00:00:00 2001 From: chrysn Date: Sat, 4 Sep 2021 23:52:47 +0200 Subject: [PATCH 1/6] net/cord doc: Rename configuration section The title is long enough that it is easily misread as "Client Configuration" and skipped when looking for common configuration. (Plus none of the other submodules of net_cord spell out the full "Core RD Endpoint and Lookup Client" module name again,a dn all say "CoRE RD Something".) --- sys/include/net/cord/config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sys/include/net/cord/config.h b/sys/include/net/cord/config.h index b6f7a47ba6..88d41453cd 100644 --- a/sys/include/net/cord/config.h +++ b/sys/include/net/cord/config.h @@ -7,7 +7,7 @@ */ /** - * @defgroup net_cord_config CoRE RD Endpoint and Lookup Client Configuration + * @defgroup net_cord_config CoRE RD Configuration * @ingroup net_cord * @brief Configuration options for CoRE RD endpoints and lookup clients * @{ From ca25ab95f92eef7ca2e013b731e34a2e603f0700 Mon Sep 17 00:00:00 2001 From: chrysn Date: Sun, 5 Sep 2021 09:22:09 +0200 Subject: [PATCH 2/6] net/cord doc: Fix unbalanced grouping --- sys/include/net/cord/config.h | 1 - 1 file changed, 1 deletion(-) diff --git a/sys/include/net/cord/config.h b/sys/include/net/cord/config.h index 88d41453cd..f61ecc3b13 100644 --- a/sys/include/net/cord/config.h +++ b/sys/include/net/cord/config.h @@ -105,7 +105,6 @@ extern "C" { #ifdef DOXYGEN #define CONFIG_CORD_EXTRAARGS #endif -/** @} */ #ifdef __cplusplus } From 7253817890efe1c482f9a17cfd1db2e0a87a9b4f Mon Sep 17 00:00:00 2001 From: chrysn Date: Sun, 5 Sep 2021 10:23:06 +0200 Subject: [PATCH 3/6] net/cord doc: Unify configuration documentation ... ... anchored both under "compile time configuration" and "Networking / CoRE RD" This makes the related configuration items visible on the same page. Co-authored-by: Martine Lenders --- sys/include/net/cord/config.h | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/sys/include/net/cord/config.h b/sys/include/net/cord/config.h index f61ecc3b13..da29fbb4a6 100644 --- a/sys/include/net/cord/config.h +++ b/sys/include/net/cord/config.h @@ -9,6 +9,7 @@ /** * @defgroup net_cord_config CoRE RD Configuration * @ingroup net_cord + * @ingroup config * @brief Configuration options for CoRE RD endpoints and lookup clients * @{ * @@ -26,11 +27,6 @@ extern "C" { #endif -/** - * @defgroup net_cord_conf CoRE RD Client compile configurations - * @ingroup config - * @{ - */ /** * @brief Default lifetime in seconds (the default is 1 day) */ @@ -44,7 +40,6 @@ extern "C" { #ifndef CONFIG_CORD_UPDATE_INTERVAL #define CONFIG_CORD_UPDATE_INTERVAL ((CONFIG_CORD_LT / 4) * 3) #endif -/** @} */ /** * @brief Delay until the RD client starts to try registering (in seconds) From 72c21f6506a82279c19aa4c467b0c478ebddba3c Mon Sep 17 00:00:00 2001 From: chrysn Date: Sun, 5 Sep 2021 10:26:27 +0200 Subject: [PATCH 4/6] net/cord doc: Fix Endpoint ID grouping The braces (which appear to do nothing) were keeping Doxygen from grouping the three "Endpoint ID defition" parameters (apparently intended to be grouped from the braces in the file) from being shown together. Moreover, they kept CONFIG_CORD_EXTRAARGS from showing. --- sys/include/net/cord/config.h | 3 --- 1 file changed, 3 deletions(-) diff --git a/sys/include/net/cord/config.h b/sys/include/net/cord/config.h index da29fbb4a6..de3e2fc7ef 100644 --- a/sys/include/net/cord/config.h +++ b/sys/include/net/cord/config.h @@ -64,13 +64,10 @@ extern "C" { #ifndef CONFIG_CORD_EP #ifdef DOXYGEN /** - * @ingroup net_cord_conf * @brief Endpoint ID definition - * @{ */ #define CONFIG_CORD_EP "MyNewEpName" //defined for doxygen documentation only #endif -/** @} */ /** * @brief Number of generated hexadecimal characters added to the ep From 418dafd40edd643c914a91deb35b8392f3b44933 Mon Sep 17 00:00:00 2001 From: chrysn Date: Sun, 5 Sep 2021 10:36:40 +0200 Subject: [PATCH 5/6] net/cord doc: Expand CONFIG_CORD_EXTRAARGS documentation --- sys/include/net/cord/config.h | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/sys/include/net/cord/config.h b/sys/include/net/cord/config.h index de3e2fc7ef..a2d5e5ccdf 100644 --- a/sys/include/net/cord/config.h +++ b/sys/include/net/cord/config.h @@ -86,7 +86,15 @@ extern "C" { /** * @brief Extra query parameters added during registration * - * Must be suitable for constructing a static array out of them. + * Must be suitable for constructing a static array out of them. Each item of + * the array is turned as a Uri-Query option. The [IANA RD Parameters subregistry] + * contains usable keys and their descriptions in entries that have an "R" in + * their "Use" column. Other keys can be used with known RD implementations. + * + * The `ep` and `lt` parameters are *not* to be set through this mechanism, but + * through @ref CONFIG_CORD_EP and @ref CONFIG_CORD_LT, respectively. + * + * [IANA RD Parameters subregistry]: https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#rd-parameters * * Example: * From 92e877b0c125ace2f23c61003303df22e493b970 Mon Sep 17 00:00:00 2001 From: chrysn Date: Sun, 5 Sep 2021 10:42:59 +0200 Subject: [PATCH 6/6] doxygen: Remove check exclusions for recent fixes --- dist/tools/doccheck/exclude_patterns | 1 - 1 file changed, 1 deletion(-) diff --git a/dist/tools/doccheck/exclude_patterns b/dist/tools/doccheck/exclude_patterns index 398900ddf1..0e94aa5f25 100644 --- a/dist/tools/doccheck/exclude_patterns +++ b/dist/tools/doccheck/exclude_patterns @@ -14280,7 +14280,6 @@ sys/include/net/coap\.h:[0-9]+: warning: Member COAP_TYPE_ACK \(macro definition sys/include/net/coap\.h:[0-9]+: warning: Member COAP_TYPE_CON \(macro definition\) of group net_coap is not documented\. sys/include/net/coap\.h:[0-9]+: warning: Member COAP_TYPE_NON \(macro definition\) of group net_coap is not documented\. sys/include/net/coap\.h:[0-9]+: warning: Member COAP_TYPE_RST \(macro definition\) of group net_coap is not documented\. -sys/include/net/cord/config\.h:[0-9]+: warning: unbalanced grouping commands sys/include/net/dhcpv6/client\.h:[0-9]+: warning: unbalanced grouping commands sys/include/net/dhcpv6\.h:[0-9]+: warning: end of file with unbalanced grouping commands sys/include/net/dns\.h:[0-9]+: warning: Member DNS_CLASS_IN \(macro definition\) of group net_dns is not documented\.