ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Doxygen template and CI to not produce warnings and errors
pull/3962/merge
Sam Grove 2017-06-07 11:18:47 -05:00 committed by GitHub
parent 01e4520548 bb2eb8b7b7
commit 744b95cc9f
18 changed files with 2520 additions and 1633 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

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

7
.travis.yml
View File

@ -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

2454
doxyfile_options Normal file
View File

File diff suppressed because it is too large Load Diff

4
doxygen_options.json
View File

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

9
features/netsocket/CellularInterface.h
View File

@ -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 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 @@ public:
#endif
/** @}*/

16
features/netsocket/NetworkInterface.h
View File

@ -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 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 @@ 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
/** @}*/

9
features/netsocket/NetworkStack.h
View File

@ -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
/** @}*/

7
features/netsocket/SocketAddress.h
View File

@ -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);

13
features/netsocket/TCPServer.h
View File

@ -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 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 @@ protected:
#endif
/** @}*/

11
features/netsocket/WiFiInterface.h
View File

@ -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
* 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;

2
features/netsocket/nsapi_ppp.h
View File

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

22
features/netsocket/nsapi_types.h
View File

@ -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 */

21
platform/ATCmdParser.h
View File

@ -80,10 +80,11 @@ public:
/**
* Constructor
*
* @param serial serial interface to use for AT commands
* @param buffer_size size of internal buffer for transaction
* @param timeout timeout of the connection
* @param debug turns on/off debug output for AT commands
* @param fh A FileHandle to a digital interface to use for AT commands
* @param output_delimiter end of command line termination
* @param buffer_size size of internal buffer for transaction
* @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

4
platform/FileHandle.h
View File

@ -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 mode, operation upon the file descriptor, e.g., 'wb+'*/
* @param fh a pointer to an opened file descriptor
* @param mode operation upon the file descriptor, e.g., 'wb+'*/
std::FILE *fdopen(FileHandle *fh, const char *mode);

4
platform/FileSystemHandle.h
View File

@ -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

10
platform/mbed_poll.h
View File

@ -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 nhfs, number of file handles
* @param timeout, timer value to timeout or -1 for loop forever
* @param fhs an array of PollFh struct carrying a FileHandle and bitmasks of events
* @param nfhs number of file handles
* @param timeout timer value to timeout or -1 for loop forever
*
* @return number of file handles selected (for which revents is non-zero).
* @return 0 if timed out with nothing selected.
* @return -1 for error.
* @return number of file handles selected (for which revents is non-zero). 0 if timed out with nothing selected. -1 for error.
*/
int poll(pollfh fhs[], unsigned nfhs, int timeout);

1512
tools/misc/Doxyfile
View File

File diff suppressed because it is too large Load Diff

47
tools/misc/docs_gen.py
View File

@ -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"))