Merge pull request #4425 from sg-/doxygen-template

Doxygen template and CI to not produce warnings and errors

Author: sg-

.gitignore

@@ -5,6 +5,7 @@ dist
 
 # MANIFEST file
 MANIFEST
+doxygen_objdb_*
 
 # Private settings
 mbed_settings.py

.travis.yml

@@ -2,6 +2,9 @@ python:
   - "2.7"
 
 script:
+  - mkdir BUILD && doxygen doxyfile_options
+  - |
+    [ -z "`doxygen doxyfile_options 2>&1`" ]
   - make -C events/equeue test clean
   - PYTHONPATH=. python tools/test/config_test/config_test.py
   - PYTHONPATH=. python tools/test/build_api/build_api_test.py
@@ -13,11 +16,13 @@ script:
   - python tools/build_travis.py
 before_install:
   - sudo add-apt-repository -y ppa:terry.guo/gcc-arm-embedded
+  - sudo add-apt-repository -y ppa:libreoffice/libreoffice-4-2
   - sudo apt-get update -qq
-  - sudo apt-get install -qq gcc-arm-none-eabi --force-yes
+  - sudo apt-get install -qq gcc-arm-none-eabi doxygen --force-yes
   # Print versions we use
   - arm-none-eabi-gcc --version
   - python --version
+  - doxygen --version
 install:
   - sudo pip install -r requirements.txt
   - sudo pip install pytest

doxyfile_options

@@ -8,5 +8,5 @@
     "PREDEFINED": "DOXYGEN_ONLY \"MBED_DEPRECATED_SINCE(f, g)=\" \"MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)=\"",
     "EXPAND_AS_DEFINED": "", 
     "SKIP_FUNCTION_MACROS": "NO",
-    "EXCLUDE_PATTERNS": "*/tools/* */TESTS/* */targets/* */features/FEATURE_*/* */features/mbedtls/* */features/nanostack/* */features/storage/* */features/unsupported/* */features/frameworks/* */features/filesystem/fat/* */BUILD/* */rtos/* */events/* */cmsis/* */hal/* */features/*"
-}
+    "EXCLUDE_PATTERNS": "*/tools/* */TESTS/* */targets/* */FEATURE_*/* */features/mbedtls/* */features/storage/* */features/unsupported/* */features/frameworks/* */features/filesystem/* */BUILD/* */rtos/* */events/* */cmsis/* */hal/* */features/FEATURES_*"
+}

doxygen_options.json

@@ -1,5 +1,3 @@
-/** \addtogroup netsocket */
-/** @{*/
 /* CellularInterface
  * Copyright (c) 2015 ARM Limited
  *
@@ -25,6 +23,7 @@
 /** CellularInterface class
  *
  *  Common interface that is shared between ethernet hardware
+ *  @addtogroup netsocket
  */
 class CellularInterface : public NetworkInterface
 {
@@ -36,8 +35,8 @@ class CellularInterface : public NetworkInterface
     /** Set the cellular network APN and credentials
      *
      *  @param apn      Optional name of the network to connect to
-     *  @param user     Optional username for the APN
-     *  @param pass     Optional password fot the APN
+     *  @param username Optional username for the APN
+     *  @param password Optional password fot the APN
      *  @return         0 on success, negative error code on failure
      */
     virtual nsapi_error_t set_credentials(const char *apn,
@@ -70,5 +69,3 @@ class CellularInterface : public NetworkInterface
 
 
 #endif
-
-/** @}*/

features/netsocket/CellularInterface.h

@@ -1,6 +1,3 @@
-
-/** \addtogroup netsocket */
-/** @{*/
 /* NetworkStack
  * Copyright (c) 2015 ARM Limited
  *
@@ -30,6 +27,7 @@ class NetworkStack;
 /** NetworkInterface class
  *
  *  Common interface that is shared between network devices
+ *  @addtogroup netsocket
  */
 class NetworkInterface {
 public:
@@ -73,10 +71,10 @@ class NetworkInterface {
      *  Implicitly disables DHCP, which can be enabled in set_dhcp.
      *  Requires that the network is disconnected.
      *
-     *  @param address  Null-terminated representation of the local IP address
-     *  @param netmask  Null-terminated representation of the local network mask
-     *  @param gateway  Null-terminated representation of the local gateway
-     *  @return         0 on success, negative error code on failure
+     *  @param ip_address Null-terminated representation of the local IP address
+     *  @param netmask    Null-terminated representation of the local network mask
+     *  @param gateway    Null-terminated representation of the local gateway
+     *  @return           0 on success, negative error code on failure
      */
     virtual nsapi_error_t set_network(
             const char *ip_address, const char *netmask, const char *gateway);
@@ -123,7 +121,7 @@ class NetworkInterface {
 
     /** Add a domain name server to list of servers to query
      *
-     *  @param addr     Destination for the host address
+     *  @param address  Destination for the host address
      *  @return         0 on success, negative error code on failure
      */
     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
@@ -146,5 +144,3 @@ class NetworkInterface {
 
 
 #endif
-
-/** @}*/

features/netsocket/NetworkInterface.h

@@ -1,6 +1,4 @@
 
-/** \addtogroup netsocket */
-/** @{*/
 /* NetworkStack
  * Copyright (c) 2015 ARM Limited
  *
@@ -31,6 +29,7 @@
  *  can connect to a network over IP. By implementing the
  *  NetworkStack, a network stack can be used as a target
  *  for instantiating network sockets.
+ *  @addtogroup netsocket
  */
 class NetworkStack
 {
@@ -63,7 +62,7 @@ class NetworkStack
 
     /** Add a domain name server to list of servers to query
      *
-     *  @param addr     Destination for the host address
+     *  @param address  Destination for the host address
      *  @return         0 on success, negative error code on failure
      */
     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
@@ -246,7 +245,7 @@ class NetworkStack
      *
      *  @param handle   Socket handle
      *  @param address  Destination for the source address or NULL
-     *  @param data     Destination buffer for data received from the host
+     *  @param buffer   Destination buffer for data received from the host
      *  @param size     Size of the buffer in bytes
      *  @return         Number of received bytes on success, negative error
      *                  code on failure
@@ -322,5 +321,3 @@ NetworkStack *nsapi_create_stack(IF *iface)
 
 
 #endif
-
-/** @}*/

features/netsocket/NetworkStack.h

@@ -1,6 +1,4 @@
 
-/** \addtogroup netsocket */
-/** @{*/
 /* SocketAddress
  * Copyright (c) 2015 ARM Limited
  *
@@ -31,6 +29,7 @@ class NetworkInterface;
 /** SocketAddress class
  *
  *  Representation of an IP address and port pair. 
+ *  @addtogroup netsocket
  */
 class SocketAddress {
 public:
@@ -66,7 +65,7 @@ class SocketAddress {
 
     /** Create a SocketAddress from an IP address and port
      *
-     *  @param host     Null-terminated representation of the IP address
+     *  @param addr     Null-terminated representation of the IP address
      *  @param port     Optional 16-bit port
      */
     SocketAddress(const char *addr, uint16_t port = 0);
@@ -81,7 +80,7 @@ class SocketAddress {
 
     /** Create a SocketAddress from another SocketAddress
      *
-     *  @param address  SocketAddress to copy
+     *  @param addr  SocketAddress to copy
      */
     SocketAddress(const SocketAddress &addr);
 

features/netsocket/SocketAddress.h

@@ -1,6 +1,4 @@
 
-/** \addtogroup netsocket */
-/** @{*/
 /* TCPServer
  * Copyright (c) 2015 ARM Limited
  *
@@ -28,7 +26,8 @@
 
 
 /** TCP socket server
-  */
+ *  @addtogroup netsocket
+ */
 class TCPServer : public Socket {
 public:
     /** Create an uninitialized socket
@@ -78,9 +77,9 @@ class TCPServer : public Socket {
      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
      *  immediately.
      *
-     *  @param socket   TCPSocket instance that will handle the incoming connection.
-     *  @param address  Destination for the remote address or NULL
-     *  @return         0 on success, negative error code on failure
+     *  @param connection TCPSocket instance that will handle the incoming connection.
+     *  @param address    Destination for the remote address or NULL
+     *  @return           0 on success, negative error code on failure
      */
     nsapi_error_t accept(TCPSocket *connection, SocketAddress *address = NULL);
 
@@ -94,5 +93,3 @@ class TCPServer : public Socket {
 
 
 #endif
-
-/** @}*/

features/netsocket/TCPServer.h

@@ -1,6 +1,4 @@
 
-/** \addtogroup netsocket */
-/** @{*/
 /* WiFiInterface
  * Copyright (c) 2015 - 2016 ARM Limited
  *
@@ -27,6 +25,7 @@
 /** WiFiInterface class
  *
  *  Common interface that is shared between WiFi devices
+ *  @addtogroup netsocket
  */
 class WiFiInterface: public NetworkInterface
 {
@@ -91,12 +90,12 @@ class WiFiInterface: public NetworkInterface
     /** Scan for available networks
      *
      *  This function will block. If the @a count is 0, function will only return count of available networks, so that
-     *  user can allocated necessary memory. If the @count is grater than 0 and the @a ap is not NULL it'll be populated
-     *  with discovered networks up to value of @a count.
+     *  user can allocated necessary memory. If the \p count is grater than 0 and the a \p res is not NULL it'll be populated
+     *  with discovered networks up to value of \p count.
      *
-     *  @param  ap       Pointer to allocated array to store discovered AP
+     *  @param  res      Pointer to allocated array to store discovered AP
      *  @param  count    Size of allocated @a res array, or 0 to only count available AP
-     *  @return          Number of entries in @a, or if @a count was 0 number of available networks,
+     *  @return          Number of entries in \p count, or if \p count was 0 number of available networks,
      *                   negative on error see @a nsapi_error
      */
     virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;

features/netsocket/WiFiInterface.h

@@ -83,4 +83,6 @@ const char *nsapi_ppp_get_gw_addr(FileHandle *stream);
 
 } //namespace mbed
 
+/** @} */
+
 #endif /* NSAPI_PPP_H_ */

features/netsocket/nsapi_ppp.h

@@ -32,7 +32,7 @@ extern "C" {
  *  Valid error codes have negative values and may
  *  be returned by any network operation.
  *
- *  @enum nsapi_error_t
+ *  @enum nsapi_error
  */
 enum nsapi_error {
     NSAPI_ERROR_OK                  =  0,        /*!< no error */
@@ -125,7 +125,7 @@ typedef enum nsapi_security {
  *
  *  The IP version specifies the type of an IP address.
  *
- *  @enum nsapi_version_t
+ *  @enum nsapi_version
  */
 typedef enum nsapi_version {
     NSAPI_UNSPEC,   /*!< Address is unspecified */
@@ -160,51 +160,51 @@ typedef void *nsapi_socket_t;
  *  The socket protocol specifies a particular protocol to
  *  be used with a newly created socket. 
  *
- *  @enum nsapi_protocol_t
+ *  @enum nsapi_protocol
  */
 typedef enum nsapi_protocol {
    NSAPI_TCP, /*!< Socket is of TCP type */
    NSAPI_UDP, /*!< Socket is of UDP type */
 } nsapi_protocol_t;
 
-/*  Enum of standardized stack option levels
+/** Enum of standardized stack option levels
  *  for use with NetworkStack::setstackopt and getstackopt.
  *
- *  @enum nsapi_stack_level_t
+ *  @enum nsapi_stack_level
  */
 typedef enum nsapi_stack_level {
     NSAPI_STACK     = 5000, /*!< Stack option level - see nsapi_stack_option_t for options */
 } nsapi_stack_level_t;
 
-/*  Enum of standardized stack option names for level NSAPI_STACK
+/** Enum of standardized stack option names for level NSAPI_STACK
  *  of NetworkStack::setstackopt and getstackopt.
  *
  *  These options may not be supported on all stacks, in which
  *  case NSAPI_ERROR_UNSUPPORTED may be returned.
  *
- *  @enum nsapi_stack_option_t
+ *  @enum nsapi_stack_option
  */
 typedef enum nsapi_stack_option {
     NSAPI_IPV4_MRU, /*!< Sets/gets size of largest IPv4 fragmented datagram to reassemble */
     NSAPI_IPV6_MRU, /*!< Sets/gets size of largest IPv6 fragmented datagram to reassemble */
 } nsapi_stack_option_t;
 
-/*  Enum of standardized socket option levels
+/** Enum of standardized socket option levels
  *  for use with Socket::setsockopt and getsockopt.
  *
- *  @enum nsapi_socket_level_t
+ *  @enum nsapi_socket_level
  */
 typedef enum nsapi_socket_level {
     NSAPI_SOCKET    = 7000, /*!< Socket option level - see nsapi_socket_option_t for options */
 } nsapi_socket_level_t;
 
-/*  Enum of standardized socket option names for level NSAPI_SOCKET
+/** Enum of standardized socket option names for level NSAPI_SOCKET
  *  of Socket::setsockopt and getsockopt.
  *
  *  These options may not be supported on all stacks, in which
  *  case NSAPI_ERROR_UNSUPPORTED may be returned.
  *
- *  @enum nsapi_socket_option_t
+ *  @enum nsapi_socket_option
  */
 typedef enum nsapi_socket_option {
     NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */