From 2eef189a0aabc73f97896e96818e7da1cc0c2b97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Th=C3=A9baudeau?= Date: Sat, 20 Jun 2015 03:04:37 +0200 Subject: [PATCH 1/2] doxygen: Fix some warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Benoît Thébaudeau --- cpu/arm/common/CMSIS/core.txt | 6 ++-- cpu/avr/dev/lanc111.c | 4 +-- cpu/avr/radio/rf230bb/halbb.c | 4 +-- cpu/stm32w108/hal/error-def.h | 8 +++-- .../hal/micro/cortexm3/compiler/gnu.h | 2 +- .../hal/micro/cortexm3/compiler/iar.h | 2 +- cpu/stm32w108/hal/micro/micro-common.h | 2 +- doc/Doxyfile | 32 +++++++++++-------- regression-tests/00-doxygen/doxyerrors.cnt | 3 +- 9 files changed, 35 insertions(+), 28 deletions(-) diff --git a/cpu/arm/common/CMSIS/core.txt b/cpu/arm/common/CMSIS/core.txt index 3ae0d00ff..b9270e199 100644 --- a/cpu/arm/common/CMSIS/core.txt +++ b/cpu/arm/common/CMSIS/core.txt @@ -34,17 +34,17 @@ */ /** - * @defgroup Cortex_M0 + * @defgroup Cortex_M0 Cortex-M0 * @ingroup cmsis */ /** - * @defgroup Cortex_M3 + * @defgroup Cortex_M3 Cortex-M3 * @ingroup cmsis */ /** - * @defgroup Cortex_M4 + * @defgroup Cortex_M4 Cortex-M4 * @ingroup cmsis */ diff --git a/cpu/avr/dev/lanc111.c b/cpu/avr/dev/lanc111.c index 28b793896..60cde63af 100644 --- a/cpu/avr/dev/lanc111.c +++ b/cpu/avr/dev/lanc111.c @@ -170,7 +170,7 @@ * \addtogroup avr * @{ */ /*! - * \defgroup xgSmscRegs + * \defgroup xgSmscRegs SMSC Registers * * @{ */ @@ -1203,6 +1203,7 @@ PROCESS_THREAD(lanc111_process, ev, data) PROCESS_END(); } #endif /* 0 */ +#if 0 /*! * \brief Send Ethernet packet. * @@ -1213,7 +1214,6 @@ PROCESS_THREAD(lanc111_process, ev, data) * * \return 0 on success, -1 in case of any errors. */ -#if 0 int LancOutput(NUTDEVICE * dev, NETBUF * nb) { static u_long mx_wait = 5000; diff --git a/cpu/avr/radio/rf230bb/halbb.c b/cpu/avr/radio/rf230bb/halbb.c index 53deb1c8a..5cd920a39 100644 --- a/cpu/avr/radio/rf230bb/halbb.c +++ b/cpu/avr/radio/rf230bb/halbb.c @@ -544,6 +544,7 @@ hal_frame_write(uint8_t *write_buffer, uint8_t length) } /*----------------------------------------------------------------------------*/ +#if 0 //Uses 80 bytes (on Raven) omit unless needed /** \brief Read SRAM * * This function reads from the SRAM of the radio transceiver. @@ -552,7 +553,6 @@ hal_frame_write(uint8_t *write_buffer, uint8_t length) * \param length Length of the read burst * \param data Pointer to buffer where data is stored. */ -#if 0 //Uses 80 bytes (on Raven) omit unless needed void hal_sram_read(uint8_t address, uint8_t length, uint8_t *data) { @@ -576,6 +576,7 @@ hal_sram_read(uint8_t address, uint8_t length, uint8_t *data) } #endif /*----------------------------------------------------------------------------*/ +#if 0 //omit unless needed /** \brief Write SRAM * * This function writes into the SRAM of the radio transceiver. It can reduce @@ -585,7 +586,6 @@ hal_sram_read(uint8_t address, uint8_t length, uint8_t *data) * \param length Length of the write burst * \param data Pointer to an array of bytes that should be written */ -#if 0 //omit unless needed void hal_sram_write(uint8_t address, uint8_t length, uint8_t *data) { diff --git a/cpu/stm32w108/hal/error-def.h b/cpu/stm32w108/hal/error-def.h index 908b60ae5..9295f7115 100644 --- a/cpu/stm32w108/hal/error-def.h +++ b/cpu/stm32w108/hal/error-def.h @@ -486,7 +486,7 @@ DEFINE_ERROR(ERR_FLASH_VERIFY_FAILED, 0x47) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** - * @description A fatal error has occured while trying to write data to the + * @brief A fatal error has occured while trying to write data to the * flash, possibly due to write protection or an invalid address. The data in * the flash cannot be trusted after this error, and it is possible this error * is the result of exceeding the life cycles of the flash. @@ -499,7 +499,7 @@ DEFINE_ERROR(ERR_FLASH_PROG_FAIL, 0x4B) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** - * @description A fatal error has occured while trying to erase flash, possibly + * @brief A fatal error has occured while trying to erase flash, possibly * due to write protection. The data in the flash cannot be trusted after * this error, and it is possible this error is the result of exceeding the * life cycles of the flash. @@ -1274,7 +1274,9 @@ DEFINE_ERROR( APPLICATION_ERROR_14, 0xFE) DEFINE_ERROR( APPLICATION_ERROR_15, 0xFF) #endif //DOXYGEN_SHOULD_SKIP_THIS -/** @} */ // END name group +/** @} */ + +/** @} END defgroup */ /** @} END addtogroup */ diff --git a/cpu/stm32w108/hal/micro/cortexm3/compiler/gnu.h b/cpu/stm32w108/hal/micro/cortexm3/compiler/gnu.h index 7783c0f96..ccdfa6199 100644 --- a/cpu/stm32w108/hal/micro/cortexm3/compiler/gnu.h +++ b/cpu/stm32w108/hal/micro/cortexm3/compiler/gnu.h @@ -7,7 +7,7 @@ * @addtogroup stm32w-cpu * @{ */ -/** @defgroup gnu +/** @defgroup gnu GNU * @brief Compiler and Platform specific definitions and typedefs for the * GNU C ARM compiler. * diff --git a/cpu/stm32w108/hal/micro/cortexm3/compiler/iar.h b/cpu/stm32w108/hal/micro/cortexm3/compiler/iar.h index c4492dd61..a057d48ca 100644 --- a/cpu/stm32w108/hal/micro/cortexm3/compiler/iar.h +++ b/cpu/stm32w108/hal/micro/cortexm3/compiler/iar.h @@ -8,7 +8,7 @@ * @addtogroup stm32w-cpu * @{ */ -/** @defgroup iar +/** @defgroup iar IAR * @brief Compiler and Platform specific definitions and typedefs for the * IAR ARM C compiler. * diff --git a/cpu/stm32w108/hal/micro/micro-common.h b/cpu/stm32w108/hal/micro/micro-common.h index db12908bf..9cba68903 100644 --- a/cpu/stm32w108/hal/micro/micro-common.h +++ b/cpu/stm32w108/hal/micro/micro-common.h @@ -9,7 +9,7 @@ * @addtogroup stm32w-cpu * @{ */ -/** @defgroup micro +/** @defgroup micro Micro * Many of the supplied example applications use these microcontroller functions. * See hal/micro/micro-common.h for source code. * diff --git a/doc/Doxyfile b/doc/Doxyfile index a9c714d73..cd0d1ac7c 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -1918,14 +1918,14 @@ MACRO_EXPANSION = YES # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES the includes files in the # INCLUDE_PATH will be searched if a #include is found. # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -SEARCH_INCLUDES = YES +SEARCH_INCLUDES = NO # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by the @@ -1950,17 +1950,23 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = CC_FUNCTION_POINTER_ARGS \ - NETSTACK_CONF_WITH_RIME \ - NETSTACK_CONF_WITH_IPV4 \ - NETSTACK_CONF_WITH_IPV6 \ - UIP_CONF_IPV6_RPL \ - UIP_TCP \ - UIP_UDP \ - UIP_CONF_ICMP6 \ - WITH_LOADER_ARCH \ - DOXYGEN \ - "ASCCMD(name, flags, args)=void CMD_ASCII(name)" +PREDEFINED = CC_FUNCTION_POINTER_ARGS:=1 \ + NETSTACK_CONF_WITH_RIME:=1 \ + NETSTACK_CONF_WITH_IPV4:=1 \ + NETSTACK_CONF_WITH_IPV6:=1 \ + UIP_CONF_IPV6_RPL:=1 \ + UIP_TCP:=1 \ + UIP_UDP:=1 \ + UIP_CONF_ICMP6:=1 \ + WITH_LOADER_ARCH:=1 \ + __attribute__(x):= \ + CC_ALIGN_ATTR(n):= \ + HTTPD_STRING_ATTR:= \ + PROGMEM:= \ + EEMEM:= \ + DOXYGEN:=1 \ + DOXYGEN_SHOULD_SKIP_THIS:=1 \ + "ASCCMD(name, flags, args):=void CMD_ASCII(name)" # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/regression-tests/00-doxygen/doxyerrors.cnt b/regression-tests/00-doxygen/doxyerrors.cnt index 360b9e4ba..a2ecc456e 100644 --- a/regression-tests/00-doxygen/doxyerrors.cnt +++ b/regression-tests/00-doxygen/doxyerrors.cnt @@ -1,2 +1 @@ -209 - +154 From b4ec0c7c1d5139672f8ff57b90a5dc6fca2a3ec9 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 20 Jun 2015 16:05:32 +0100 Subject: [PATCH 2/2] Remove doxygen explicit links to non-existing symbols Parts of the stm32w108 doxygen comments have explicit links to symbols that do not exist anywhere in our source base, let alone be documented. This is likely to be caused by a partial import of manufacturer libraries in the Contiki source tree. These links were previously not generating warnings in the doxygen log because we were not defining `DOXYGEN_SHOULD_SKIP_THIS` and they were thus being skipped altogether by the doxygen pre-processor. Defining `DOXYGEN_SHOULD_SKIP_THIS` causes those doxygen comments to get processed and to thus generate warnings. This commit removes explicit links to non-existent symbols and updates `doxyerrors.cnt` accordingly. --- cpu/stm32w108/hal/error-def.h | 32 +++++++++++----------- regression-tests/00-doxygen/doxyerrors.cnt | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/cpu/stm32w108/hal/error-def.h b/cpu/stm32w108/hal/error-def.h index 9295f7115..a3a38ed21 100644 --- a/cpu/stm32w108/hal/error-def.h +++ b/cpu/stm32w108/hal/error-def.h @@ -363,9 +363,9 @@ DEFINE_ERROR(MAC_INDIRECT_TIMEOUT, 0x42) /** * @brief The Simulated EEPROM is telling the application that there * is at least one flash page to be erased. The GREEN status means the - * current page has not filled above the ::ERASE_CRITICAL_THRESHOLD. + * current page has not filled above the ERASE_CRITICAL_THRESHOLD. * - * The application should call the function ::halSimEepromErasePage() when it can + * The application should call the function halSimEepromErasePage() when it can * to erase a page. */ #define ST_SIM_EEPROM_ERASE_PAGE_GREEN(0x43) @@ -378,10 +378,10 @@ DEFINE_ERROR(SIM_EEPROM_ERASE_PAGE_GREEN, 0x43) /** * @brief The Simulated EEPROM is telling the application that there * is at least one flash page to be erased. The RED status means the - * current page has filled above the ::ERASE_CRITICAL_THRESHOLD. + * current page has filled above the ERASE_CRITICAL_THRESHOLD. * * Due to the shrinking availablity of write space, there is a danger of - * data loss. The application must call the function ::halSimEepromErasePage() + * data loss. The application must call the function halSimEepromErasePage() * as soon as possible to erase a page. */ #define ST_SIM_EEPROM_ERASE_PAGE_RED(0x44) @@ -394,9 +394,9 @@ DEFINE_ERROR(SIM_EEPROM_ERASE_PAGE_RED, 0x44) /** * @brief The Simulated EEPROM has run out of room to write any new data * and the data trying to be set has been lost. This error code is the - * result of ignoring the ::SIM_EEPROM_ERASE_PAGE_RED error code. + * result of ignoring the ::ST_SIM_EEPROM_ERASE_PAGE_RED error code. * - * The application must call the function ::halSimEepromErasePage() to make room for + * The application must call the function halSimEepromErasePage() to make room for * any further calls to set a token. */ #define ST_SIM_EEPROM_FULL(0x45) @@ -440,8 +440,8 @@ DEFINE_ERROR(SIM_EEPROM_INIT_2_FAILED, 0x49) /** * @brief Attempt 3 to initialize the Simulated EEPROM has failed. * - * This failure means one or both of the tokens ::TOKEN_MFG_NVDATA_VERSION or - * ::TOKEN_STACK_NVDATA_VERSION were incorrect and the token system failed to + * This failure means one or both of the tokens TOKEN_MFG_NVDATA_VERSION or + * TOKEN_STACK_NVDATA_VERSION were incorrect and the token system failed to * properly reload default tokens and reset the Simulated EEPROM. */ #define ST_SIM_EEPROM_INIT_3_FAILED(0x4A) @@ -626,7 +626,7 @@ DEFINE_ERROR(COST_NOT_KNOWN, 0x71) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** * @brief The maximum number of in-flight messages (i.e. - * ::ST_APS_UNICAST_MESSAGE_COUNT) has been reached. + * ST_APS_UNICAST_MESSAGE_COUNT) has been reached. */ #define ST_MAX_MESSAGE_LIMIT_REACHED(0x72) #else @@ -820,7 +820,7 @@ DEFINE_ERROR(PHY_ACK_RECEIVED, 0x8F) /** * @name Return Codes Passed to stStackStatusHandler() - * See also ::stStackStatusHandler(). + * See also stStackStatusHandler(). * * @{ */ @@ -882,7 +882,7 @@ DEFINE_ERROR(CANNOT_JOIN_AS_ROUTER, 0x98) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** @brief The local node ID has changed. The application can obtain the new - * node ID by calling ::stGetNodeId(). + * node ID by calling stGetNodeId(). */ #define ST_NODE_ID_CHANGED(0x99) #else @@ -892,7 +892,7 @@ DEFINE_ERROR(NODE_ID_CHANGED, 0x99) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** @brief The local PAN ID has changed. The application can obtain the new PAN - * ID by calling ::stGetPanId(). + * ID by calling stGetPanId(). */ #define ST_PAN_ID_CHANGED(0x9A) #else @@ -920,7 +920,7 @@ DEFINE_ERROR(NO_BEACONS, 0xAB) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** @brief An attempt was made to join a Secured Network using a pre-configured * key, but the Trust Center sent back a Network Key in-the-clear when - * an encrypted Network Key was required. (::ST_REQUIRE_ENCRYPTED_KEY). + * an encrypted Network Key was required. (ST_REQUIRE_ENCRYPTED_KEY). */ #define ST_RECEIVED_KEY_IN_THE_CLEAR(0xAC) #else @@ -940,7 +940,7 @@ DEFINE_ERROR(NO_NETWORK_KEY_RECEIVED, 0xAD) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** @brief After a device joined a Secured Network, a Link Key was requested - * (::ST_GET_LINK_KEY_WHEN_JOINING) but no response was ever received. + * (ST_GET_LINK_KEY_WHEN_JOINING) but no response was ever received. */ #define ST_NO_LINK_KEY_RECEIVED(0xAE) #else @@ -978,7 +978,7 @@ DEFINE_ERROR(KEY_INVALID, 0xB2) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** - * @brief The chosen security level (the value of ::ST_SECURITY_LEVEL) + * @brief The chosen security level (the value of ST_SECURITY_LEVEL) * is not supported by the stack. */ #define ST_INVALID_SECURITY_LEVEL(0x95) @@ -1011,7 +1011,7 @@ DEFINE_ERROR(INVALID_SECURITY_LEVEL, 0x95) #ifdef DOXYGEN_SHOULD_SKIP_THIS /** @brief There was an attempt to form or join a network with security - * without calling ::stSetInitialSecurityState() first. + * without calling stSetInitialSecurityState() first. */ #define ST_SECURITY_STATE_NOT_SET(0xA8) #else diff --git a/regression-tests/00-doxygen/doxyerrors.cnt b/regression-tests/00-doxygen/doxyerrors.cnt index a2ecc456e..405e2afe8 100644 --- a/regression-tests/00-doxygen/doxyerrors.cnt +++ b/regression-tests/00-doxygen/doxyerrors.cnt @@ -1 +1 @@ -154 +134