Merge pull request #1344 from tsparber/fix-doxygen

doxygen: Fixed all warnings
2015-11-30 22:07:15 +01:00 · 2015-11-30 22:07:15 +01:00 · ebc8d9fb1c
commit ebc8d9fb1c
parent f0c3d29e8a 8792ba16b3
39 changed files with 278 additions and 222 deletions
--- a/cpu/stm32w108/hal/micro/cortexm3/mfg-token.h
+++ b/cpu/stm32w108/hal/micro/cortexm3/mfg-token.h
@ -7,6 +7,7 @@
 #ifndef MFG_TOKEN_H_
 #define MFG_TOKEN_H_

+#ifndef DOXYGEN_SHOULD_SKIP_THIS

 // The manufacturing tokens live in the Info Blocks, while all other tokens
 // live in the Simulated EEPROM.  This requires the token names to be defined
@ -20,10 +21,13 @@
 * that point to the correct location in the Info Blocks.  (This is the
 * extern, the actual definition is found in hal/micro/cortexm3/token.c)
 *
- * \param name: The name of the token.
- *
- * \param TOKEN_##name##_ADDRESS: The address in EEPROM at which the token
- * will be stored.  This parameter is generated with a macro above.
+ * \param name:       The name of the token.
+ * \param creator:    The manufacturing creators.
+ * \param iscnt:
+ * \param isidx:
+ * \param type:       The token type.  The types are found in token-stack.h.
+ * \param arraysize:  The number of elements in an indexed token (arraysize=1
+ *                    for scalar tokens).
 */
 #define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...) \
  extern const uint16_t TOKEN_##name;
@ -34,9 +38,13 @@
 * \brief Macro for translating token definitions into size variables.
 * This provides a convenience for abstracting the 'sizeof(type)' anywhere.
 *
- * \param name: The name of the token.
- *
- * \param type: The token type.  The types are found in token-stack.h.
+ * \param name:       The name of the token.
+ * \param creator:    The manufacturing creators.
+ * \param iscnt:
+ * \param isidx:
+ * \param type:       The token type.  The types are found in token-stack.h.
+ * \param arraysize:  The number of elements in an indexed token (arraysize=1
+ *                    for scalar tokens).
 */
 #define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...) \
  TOKEN_##name##_SIZE = sizeof(type),
@ -49,12 +57,16 @@
 /**
 * \brief Macro for typedef'ing the CamelCase token type found in
 * token-stack.h to a capitalized TOKEN style name that ends in _TYPE.
- * This macro allows other macros below to use 'token##_TYPE' to declare
+ * This macro allows other macros below to use 'token\#\#_TYPE' to declare
 * a local copy of that token.
 *
- * \param name: The name of the token.
- *
- * \param type: The token type.  The types are found in token-stack.h.
+ * \param name:       The name of the token.
+ * \param creator:    The manufacturing creators.
+ * \param iscnt:
+ * \param isidx:
+ * \param type:       The token type.  The types are found in token-stack.h.
+ * \param arraysize:  The number of elements in an indexed token (arraysize=1
+ *                    for scalar tokens).
 */
 #define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...) \
  typedef type TOKEN_##name##_TYPE;
@ -70,8 +82,7 @@
 * subsequent tokens to align against.  ( See hal/micro/cortexm3/token.c for
 * the instances of TOKEN_NEXT_ADDRESS() );
 *
- * \param region: The name to give to the element in the address enum..
- *
+ * \param region: The name to give to the element in the address enum.
 * \param address: The address in EEPROM where the region begins.
 */
 #define TOKEN_NEXT_ADDRESS(region, address)      \
@ -80,14 +91,17 @@
 /**
 * \brief Macro for creating ADDRESS and END elements for each token in
 * the enum below.  The ADDRESS element is linked to from the the normal
- * TOKEN_##name macro and provides the value passed into the internal token
+ * TOKEN_\#\#name macro and provides the value passed into the internal token
 * system calls.  The END element is a placeholder providing the starting
 * point for the ADDRESS of the next dynamically positioned token.
 *
- * \param name: The name of the token.
- *
- * \param arraysize: The number of elements in an indexed token (arraysize=1
- * for scalar tokens).
+ * \param name:       The name of the token.
+ * \param creator:    The manufacturing creators.
+ * \param iscnt:
+ * \param isidx:
+ * \param type:       The token type.  The types are found in token-stack.h.
+ * \param arraysize:  The number of elements in an indexed token (arraysize=1
+ *                    for scalar tokens).
 */
 #define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...) \
  TOKEN_##name##_ADDRESS,                                      \
@ -106,8 +120,6 @@ enum {

 #undef DEFINETOKENS

-
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 /**
 * \brief Copies the token value from non-volatile storage into a RAM
 * location.  This is the internal function that the exposed API
--- a/cpu/stm32w108/hal/micro/cortexm3/nvm.h
+++ b/cpu/stm32w108/hal/micro/cortexm3/nvm.h
@ -14,8 +14,7 @@
 * @addtogroup stm32w-cpu
 * @{ */

-/** @defgroup nvm
- * @brief Cortex-M3 Non-Volatile Memory data storage system.
+/** @defgroup nvm Cortex-M3 Non-Volatile Memory data storage system.
 *
 * This header defines the API for NVM data storage.  This header also
 * describes the algorithm behind the NVM data storage system with notes
--- a/cpu/stm32w108/hal/micro/cortexm3/uart.h
+++ b/cpu/stm32w108/hal/micro/cortexm3/uart.h
@ -32,8 +32,8 @@ typedef enum
 *
 * @param parity    The type of parity used for communication.
 *                  See the SerialParity enum for possible values
- * 
- * @return stopbits The number of stop bits used for communication.
+ *
+ * @param stopbits  The number of stop bits used for communication.
 *                  Valid values are 1 or 2
 */
 void uartInit(uint32_t baudrate, uint8_t databits, SerialParity parity, uint8_t stopbits);
--- a/cpu/stm32w108/hal/micro/generic/compiler/platform-common.h
+++ b/cpu/stm32w108/hal/micro/generic/compiler/platform-common.h
@ -15,7 +15,7 @@
 * @{ */

 /** \file hal/micro/generic/compiler/platform-common.h
- * See \ref platform_common for detailed documentation.
+ * See platform_common.h for detailed documentation.
 *
 * <!--(C) COPYRIGHT 2010 STMicroelectronics. All rights reserved.        -->
 */
--- a/cpu/stm32w108/hal/micro/micro-common.h
+++ b/cpu/stm32w108/hal/micro/micro-common.h
@ -70,38 +70,43 @@ void halInternalDisableWatchDog(uint8_t magicKey);
 */
 boolean halInternalWatchDogEnabled( void );

-#ifdef DOXYGEN_SHOULD_SKIP_THIS
 /** @brief Enumerations for the possible microcontroller sleep modes.
- * - SLEEPMODE_RUNNING
- *     Everything is active and running.  In practice this mode is not
- *     used, but it is defined for completeness of information.
- * - SLEEPMODE_IDLE
- *     Only the CPU is idled.  The rest of the chip continues runing
- *     normally.  The chip will wake from any interrupt.
- * - SLEEPMODE_WAKETIMER
- *     The sleep timer clock sources remain running.  The RC is always
- *     running and the 32kHz XTAL depends on the board header.  Wakeup
- *     is possible from both GPIO and the sleep timer.  System time
- *     is maintained.  The sleep timer is assumed to be configured
- *     properly for wake events.
- * - SLEEPMODE_MAINTAINTIMER
- *     The sleep timer clock sources remain running.  The RC is always
- *     running and the 32kHz XTAL depends on the board header.  Wakeup
- *     is possible from only GPIO.  System time is maintained.
- * - SLEEPMODE_NOTIMER
- *     The sleep timer clock sources (both RC and XTAL) are turned off.
- *     Wakeup is possible from only GPIO.  System time is lost.
 */
+#ifdef DOXYGEN_SHOULD_SKIP_THIS
 enum SleepModes
 #else
 typedef uint8_t SleepModes;
 enum
 #endif
 {
+  /**
+   * Everything is active and running.  In practice this mode is not
+   * used, but it is defined for completeness of information.
+   */
  SLEEPMODE_RUNNING = 0,
+  /**
+   * Oly the CPU is idled.  The rest of the chip continues runing
+   * normally.  The chip will wake from any interrupt.
+   */
  SLEEPMODE_IDLE = 1,
+  /**
+   * The sleep timer clock sources remain running.  The RC is always
+   * running and the 32kHz XTAL depends on the board header.  Wakeup
+   * is possible from both GPIO and the sleep timer.  System time
+   * is maintained.  The sleep timer is assumed to be configured
+   * properly for wake events.
+   */
  SLEEPMODE_WAKETIMER = 2,
+  /**
+   * The sleep timer clock sources remain running.  The RC is always
+   * running and the 32kHz XTAL depends on the board header.  Wakeup
+   * is possible from only GPIO.  System time is maintained.
+   */
  SLEEPMODE_MAINTAINTIMER = 3,
+  /**
+   * The sleep timer clock sources (both RC and XTAL) are turned off.
+   * Wakeup is possible from only GPIO.  System time is lost.
+   */
  SLEEPMODE_NOTIMER = 4,
 };

@ -128,15 +133,15 @@ void halCommonDelayMicroseconds(uint16_t us);
 * and if yes it will jump into it according to the user parameters.
 *
 *
- * @param mode  The bootloader mode, 0 UART mode, 1 RF mode. All other
- * values are reserved
+ * @param mode     The bootloader mode, 0 UART mode, 1 RF mode. All other
+ *                 values are reserved
 * @param channel  The channel where the booloader will operate. 0 means
- * default channel (only vaild for RF mode).
- * @param panID  The panID where the booloader will operate. 0xFFFF means
- * default panID (only vaild for RF mode).
+ *                 default channel (only vaild for RF mode).
+ * @param panID    The panID where the booloader will operate. 0xFFFF means
+ *                 default panID (only vaild for RF mode).
 * @return An error code or it will never return.
 */
-StStatus halBootloaderStart(uint8_t mode, uint8_t channel, uint16_t panId);
+StStatus halBootloaderStart(uint8_t mode, uint8_t channel, uint16_t panID);

 #ifdef CORTEXM3_STM32F103
 #include "micro/cortexm3/stm32f103ret/micro-specific.h"
--- a/cpu/stm32w108/hal/micro/system-timer.h
+++ b/cpu/stm32w108/hal/micro/system-timer.h
@ -10,7 +10,7 @@
 * @addtogroup stm32w-cpu
 * @{ */

-/** @defgroup system_timer
+/** @defgroup system_timer System Timer
 * @brief Functions that provide access to the system clock.
 *
 * A single system tick (as returned by ::halCommonGetInt16uMillisecondTick() and