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

Doxygen template and CI to not produce warnings and errors

.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

doxygen_options.json

@@ -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_*"
 }

features/netsocket/CellularInterface.h

@@ -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 @@ public:
     /** 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 username Optional username for the APN
-     *  @param pass     Optional password fot 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 @@ public:
 
 
 #endif
-
-/** @}*/

features/netsocket/NetworkInterface.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 @@ public:
      *  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 ip_address Null-terminated representation of the local IP address
-     *  @param netmask  Null-terminated representation of the local network mask
+     *  @param netmask    Null-terminated representation of the local network mask
-     *  @param gateway  Null-terminated representation of the local gateway
+     *  @param gateway    Null-terminated representation of the local gateway
-     *  @return         0 on success, negative error code on failure
+     *  @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 @@ public:
 
     /** 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 @@ protected:
 
 
 #endif
-
-/** @}*/

features/netsocket/NetworkStack.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 @@ public:
 
     /** 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 @@ protected:
      *
      *  @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/SocketAddress.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 @@ public:
 
     /** 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 @@ public:
 
     /** Create a SocketAddress from another SocketAddress
      *
-     *  @param address  SocketAddress to copy
+     *  @param addr  SocketAddress to copy
      */
     SocketAddress(const SocketAddress &addr);
    

features/netsocket/TCPServer.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 @@ public:
      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
      *  immediately.
      *
-     *  @param socket   TCPSocket instance that will handle the incoming connection.
+     *  @param connection TCPSocket instance that will handle the incoming connection.
-     *  @param address  Destination for the remote address or NULL
+     *  @param address    Destination for the remote address or NULL
-     *  @return         0 on success, negative error code on failure
+     *  @return           0 on success, negative error code on failure
      */
     nsapi_error_t accept(TCPSocket *connection, SocketAddress *address = NULL);
 
@@ -94,5 +93,3 @@ protected:
 
 
 #endif
-
-/** @}*/

features/netsocket/WiFiInterface.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 @@ public:
     /** 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
+     *  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 @a count.
+     *  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/nsapi_ppp.h

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

features/netsocket/nsapi_types.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 */

platform/ATCmdParser.h

@@ -80,10 +80,11 @@ public:
     /**
      * Constructor
      *
-     * @param serial         serial interface to use for AT commands
+     * @param fh A FileHandle to a digital interface to use for AT commands
-     * @param buffer_size    size of internal buffer for transaction
+     * @param output_delimiter end of command line termination
-     * @param timeout        timeout of the connection
+     * @param buffer_size size of internal buffer for transaction
-     * @param debug          turns on/off debug output for AT commands
+     * @param timeout timeout of the connection
+     * @param debug turns on/off debug output for AT commands
      */
     ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r",
              int buffer_size = 256, int timeout = 8000, bool debug = false)
@@ -135,7 +136,7 @@ public:
     /**
      * Sets string of characters to use as line delimiters
      *
-     * @param delimiter string of characters to use as line delimiters
+     * @param output_delimiter string of characters to use as line delimiters
      */
     void set_delimiter(const char *output_delimiter)
     {
@@ -149,7 +150,7 @@ public:
      * Please use set_delimiter(const char *) API only from now on.
      * Sets string of characters to use as line delimiters
      *
-     * @param delimiter string of characters to use as line delimiters
+     * @param output_delimiter string of characters to use as line delimiters
      */
     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
     void setDelimiter(const char *output_delimiter)
@@ -184,7 +185,7 @@ public:
      * Sends an AT command
      *
      * Sends a formatted command using printf style formatting
-     * @see ::printf
+     * @see printf
      *
      * @param command printf-like format string of command to send which
      *                is appended with a newline
@@ -199,7 +200,7 @@ public:
      * Receive an AT response
      *
      * Receives a formatted response using scanf style formatting
-     * @see ::scanf
+     * @see scanf
      *
      * Responses are parsed line at a time.
      * Any received data that does not match the response is ignored until
@@ -248,7 +249,7 @@ public:
 
     /**
      * Direct printf to underlying stream
-     * @see ::printf
+     * @see printf
      *
      * @param format format string to pass to printf
      * @param ... arguments to printf
@@ -260,7 +261,7 @@ public:
 
     /**
      * Direct scanf on underlying stream
-     * @see ::scanf
+     * @see scanf
      *
      * @param format format string to pass to scanf
      * @param ... arguments to scanf

platform/FileHandle.h

@@ -242,8 +242,8 @@ public:
  *  Returns a pointer to std::FILE.
  *  It associates a Stream to an already opened file descriptor (FileHandle)
  *
- *  @param fh, a pointer to an opened file descriptor
+ *  @param fh a pointer to an opened file descriptor
- *  @param mode, operation upon the file descriptor, e.g., 'wb+'*/
+ *  @param mode operation upon the file descriptor, e.g., 'wb+'*/
 
 std::FILE *fdopen(FileHandle *fh, const char *mode);
 

platform/FileSystemHandle.h

@@ -33,7 +33,7 @@ namespace mbed {
  *  Implementations must define at least open (the default definitions
  *  of the rest of the functions just return error values).
  *
- * @Note Synchronization level: Set by subclass
+ * @note Synchronization level: Set by subclass
  */
 class FileSystemHandle {
 public:
@@ -44,7 +44,7 @@ public:
     /** Open a file on the filesystem
      *
      *  @param file     Destination for the handle to a newly created file
-     *  @param path     The name of the file to open
+     *  @param filename The name of the file to open
      *  @param flags    The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
      *                  bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
      *  @return         0 on success, negative error code on failure

platform/mbed_poll.h

@@ -39,13 +39,11 @@ struct pollfh {
  * For every file handle provided, poll() examines it for any events registered for that particular
  * file handle.
  *
- * @param fhs,     an array of PollFh struct carrying a FileHandle and bitmasks of events
+ * @param fhs     an array of PollFh struct carrying a FileHandle and bitmasks of events
- * @param nhfs,    number of file handles
+ * @param nfhs    number of file handles
- * @param timeout, timer value to timeout or -1 for loop forever
+ * @param timeout timer value to timeout or -1 for loop forever
  *
- * @return number of file handles selected (for which revents is non-zero).
+ * @return number of file handles selected (for which revents is non-zero). 0 if timed out with nothing selected. -1 for error.
- * @return 0 if timed out with nothing selected.
- * @return -1 for error.
  */
 int poll(pollfh fhs[], unsigned nfhs, int timeout);
 

tools/misc/docs_gen.py

@@ -1,47 +0,0 @@
-"""An api for generating documentation from the codebase
-"""
-
-from os.path import dirname, join
-from os import sep
-from re import compile
-
-import subprocess
-
-def generate_documentation(dirs, output_dir):
-    """Use doxygen to generate the documentation
-
-    Positional arguments:
-    dirs - the directories that doxygen should scan for documentation
-    output_dir - location of the documentation after the return of this function
-    """
-    print dirs
-    with open(join(dirname(__file__), "Doxyfile")) as doxyfile:
-        proc = subprocess.Popen(["doxygen", "-"], stdin=subprocess.PIPE)
-        proc.stdin.write(doxyfile.read())
-        proc.stdin.write("OUTPUT_DIRECTORY={}\n".format(output_dir))
-        proc.stdin.write("INPUT={}".format(" ".join(dirs)))
-        proc.stdin.close()
-        proc.wait()
-
-EXCLUDES = ["targets", "features/FEATURE", "features/mbedtls",
-           "features/nanostack", "features/storage"]
-
-def is_not_excluded(src):
-    return all(exclude not in src for exclude in EXCLUDES)
-
-if __name__ == "__main__":
-    import sys
-    from os.path import abspath, dirname, join
-    # Be sure that the tools directory is in the search path
-    ROOT = abspath(join(dirname(__file__), "..", ".."))
-    sys.path.insert(0, ROOT)
-
-    from tools.toolchains.gcc import GCC_ARM
-    from tools.targets import TARGET_MAP
-    toolchain = GCC_ARM(TARGET_MAP["Super_Target"])
-    resources = toolchain.scan_resources(".")
-    generate_documentation(filter(is_not_excluded,
-                                  sum(map(lambda x:x.headers,
-                                          resources.features.values()),
-                                      resources.headers)),
-                           join(dirname(dirname(__file__)), "mbed-docs"))