From 106e459a6401ad947b61197ab3b80cae6a5cebcc Mon Sep 17 00:00:00 2001 From: Christopher Haster Date: Sun, 13 Mar 2016 06:32:02 -0500 Subject: [PATCH] Adopt mbed style doxygen comments per @0xc0170 --- net/NetworkSocketAPI/NetworkInterface.h | 208 ++++++++++++------------ net/NetworkSocketAPI/Socket.h | 36 ++-- net/NetworkSocketAPI/SocketAddress.h | 30 ++-- net/NetworkSocketAPI/TCPServer.h | 28 ++-- net/NetworkSocketAPI/TCPSocket.h | 55 +++---- net/NetworkSocketAPI/UDPSocket.h | 49 +++--- net/NetworkSocketAPI/WiFiInterface.h | 16 +- 7 files changed, 209 insertions(+), 213 deletions(-) diff --git a/net/NetworkSocketAPI/NetworkInterface.h b/net/NetworkSocketAPI/NetworkInterface.h index 654e3a5e55..28ad41e28e 100644 --- a/net/NetworkSocketAPI/NetworkInterface.h +++ b/net/NetworkSocketAPI/NetworkInterface.h @@ -20,9 +20,8 @@ #include "mbed.h" #include "SocketAddress.h" -/** +/** Enum of standardized error codes * @enum ns_error_t - * @brief enum of standardized error codes */ enum nsapi_error_t { NSAPI_ERROR_WOULD_BLOCK = -3001, /*!< no data is not available but call is non-blocking */ @@ -37,16 +36,15 @@ enum nsapi_error_t { NSAPI_ERROR_DEVICE_ERROR = -3010, /*!< failure interfacing with the network procesor */ }; -/** +/** Enum of available options * @enum ns_opt_t - * @brief enum of available options */ enum ns_opt_t { }; /** Enum of socket protocols -/enum protocol_t -*/ + * @enum protocol_t + */ enum nsapi_protocol_t { NSAPI_TCP, /*!< Socket is of TCP type */ NSAPI_UDP, /*!< Socket is of UDP type */ @@ -62,27 +60,27 @@ public: virtual ~NetworkInterface() {}; /** Get the internally stored IP address - /return IP address of the interface or null if not yet connected - */ + * @return IP address of the interface or null if not yet connected + */ virtual const char *get_ip_address() = 0; /** Get the internally stored MAC address - /return MAC address of the interface - */ + * @return MAC address of the interface + */ virtual const char *get_mac_address() = 0; /** Get the current status of the interface - /return true if connected - */ + * @return true if connected + */ virtual bool is_connected() { return get_ip_address() != NULL; } /** Looks up the specified host's IP address - /param name Hostname to lookup - /param dest Destination for IP address, must have space for SocketAddress::IP_SIZE - /return 0 on success, negative on failure - */ + * @param name Hostname to lookup + * @param dest Destination for IP address, must have space for SocketAddress::IP_SIZE + * @return 0 on success, negative on failure + */ virtual int gethostbyname(const char *name, char *dest); protected: @@ -92,143 +90,143 @@ protected: friend class TCPServer; /** Create a socket - /param proto The type of socket to open, TCP or UDP - /return The alocated socket or null on failure - */ + * @param proto The type of socket to open, TCP or UDP + * @return The alocated socket or null on failure + */ virtual void *socket_create(nsapi_protocol_t proto) = 0; /** Destroy a socket - /param socket Previously allocated socket - */ + * @param socket Previously allocated socket + */ virtual void socket_destroy(void *handle) = 0; /** Set socket options - \param handle Socket handle - \param optname Option ID - \param optval Option value - \param optlen Length of the option value - \return 0 on success, negative on failure - */ + * @param handle Socket handle + * @param optname Option ID + * @param optval Option value + * @param optlen Length of the option value + * @return 0 on success, negative on failure + */ virtual int socket_set_option(void *handle, int optname, const void *optval, unsigned int optlen) = 0; /** Get socket options - \param handle Socket handle - \param optname Option ID - \param optval Buffer pointer where to write the option value - \param optlen Length of the option value - \return 0 on success, negative on failure - */ + * @param handle Socket handle + * @param optname Option ID + * @param optval Buffer pointer where to write the option value + * @param optlen Length of the option value + * @return 0 on success, negative on failure + */ virtual int socket_get_option(void *handle, int optname, void *optval, unsigned int *optlen) = 0; /** Bind a server socket to a specific port - \param handle Socket handle - \param port The port to listen for incoming connections on - \return 0 on success, negative on failure. - */ + * @param handle Socket handle + * @param port The port to listen for incoming connections on + * @return 0 on success, negative on failure. + */ virtual int socket_bind(void *handle, int port) = 0; /** Start listening for incoming connections - \param handle Socket handle - \param backlog Number of pending connections that can be queued up at any - one time [Default: 1] - \return 0 on success, negative on failure - */ + * @param handle Socket handle + * @param backlog Number of pending connections that can be queued up at any + * one time [Default: 1] + * @return 0 on success, negative on failure + */ virtual int socket_listen(void *handle, int backlog) = 0; /** Connects this TCP socket to the server - \param handle Socket handle - \param address SocketAddress to connect to - \return 0 on success, negative on failure - */ + * @param handle Socket handle + * @param address SocketAddress to connect to + * @return 0 on success, negative on failure + */ virtual int socket_connect(void *handle, const SocketAddress &address) = 0; /** Check if the socket is connected - \param handle Socket handle - \return true if connected, false otherwise - */ + * @param handle Socket handle + * @return true if connected, false otherwise + */ virtual bool socket_is_connected(void *handle) = 0; /** Accept a new connection. - \param handle Socket handle - \param socket A TCPSocket instance that will handle the incoming connection. - \return 0 on success, negative on failure. - \note This call is not-blocking, if this call would block, must - immediately return NSAPI_ERROR_WOULD_WAIT - */ + * @param handle Socket handle + * @param socket A TCPSocket instance that will handle the incoming connection. + * @return 0 on success, negative on failure. + * @note This call is not-blocking, if this call would block, must + * immediately return NSAPI_ERROR_WOULD_WAIT + */ virtual int socket_accept(void *handle, void **connection) = 0; /** Send data to the remote host - \param handle Socket handle - \param data The buffer to send to the host - \param size The length of the buffer to send - \return Number of written bytes on success, negative on failure - \note This call is not-blocking, if this call would block, must - immediately return NSAPI_ERROR_WOULD_WAIT - */ + * @param handle Socket handle + * @param data The buffer to send to the host + * @param size The length of the buffer to send + * @return Number of written bytes on success, negative on failure + * @note This call is not-blocking, if this call would block, must + * immediately return NSAPI_ERROR_WOULD_WAIT + */ virtual int socket_send(void *handle, const void *data, unsigned size) = 0; /** Receive data from the remote host - \param handle Socket handle - \param data The buffer in which to store the data received from the host - \param size The maximum length of the buffer - \return Number of received bytes on success, negative on failure - \note This call is not-blocking, if this call would block, must - immediately return NSAPI_ERROR_WOULD_WAIT - */ + * @param handle Socket handle + * @param data The buffer in which to store the data received from the host + * @param size The maximum length of the buffer + * @return Number of received bytes on success, negative on failure + * @note This call is not-blocking, if this call would block, must + * immediately return NSAPI_ERROR_WOULD_WAIT + */ virtual int socket_recv(void *handle, void *data, unsigned size) = 0; /** Send a packet to a remote endpoint - \param handle Socket handle - \param address The remote SocketAddress - \param data The packet to be sent - \param size The length of the packet to be sent - \return the number of written bytes on success, negative on failure - \note This call is not-blocking, if this call would block, must - immediately return NSAPI_ERROR_WOULD_WAIT - */ + * @param handle Socket handle + * @param address The remote SocketAddress + * @param data The packet to be sent + * @param size The length of the packet to be sent + * @return the number of written bytes on success, negative on failure + * @note This call is not-blocking, if this call would block, must + * immediately return NSAPI_ERROR_WOULD_WAIT + */ virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size) = 0; /** Receive a packet from a remote endpoint - \param handle Socket handle - \param address Destination for the remote SocketAddress or null - \param buffer The buffer for storing the incoming packet data - If a packet is too long to fit in the supplied buffer, - excess bytes are discarded - \param size The length of the buffer - \return the number of received bytes on success, negative on failure - \note This call is not-blocking, if this call would block, must - immediately return NSAPI_ERROR_WOULD_WAIT - */ + * @param handle Socket handle + * @param address Destination for the remote SocketAddress or null + * @param buffer The buffer for storing the incoming packet data + * If a packet is too long to fit in the supplied buffer, + * excess bytes are discarded + * @param size The length of the buffer + * @return the number of received bytes on success, negative on failure + * @note This call is not-blocking, if this call would block, must + * immediately return NSAPI_ERROR_WOULD_WAIT + */ virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size) = 0; /** Close the socket - \param handle Socket handle - \param shutdown free the left-over data in message queues - */ + * @param handle Socket handle + * @param shutdown free the left-over data in message queues + */ virtual int socket_close(void *handle, bool shutdown) = 0; /** Register a callback on when a new connection is ready - \param handle Socket handle - \param callback Function to call when accept will succeed, may be called in - interrupt context. - \param id Argument to pass to callback - */ + * @param handle Socket handle + * @param callback Function to call when accept will succeed, may be called in + * interrupt context. + * @param id Argument to pass to callback + */ virtual void socket_attach_accept(void *handle, void (*callback)(void *), void *id) = 0; /** Register a callback on when send is ready - \param handle Socket handle - \param callback Function to call when accept will succeed, may be called in - interrupt context. - \param id Argument to pass to callback - */ + * @param handle Socket handle + * @param callback Function to call when accept will succeed, may be called in + * interrupt context. + * @param id Argument to pass to callback + */ virtual void socket_attach_send(void *handle, void (*callback)(void *), void *id) = 0; /** Register a callback on when recv is ready - \param handle Socket handle - \param callback Function to call when accept will succeed, may be called in - interrupt context. - \param id Argument to pass to callback - */ + * @param handle Socket handle + * @param callback Function to call when accept will succeed, may be called in + * interrupt context. + * @param id Argument to pass to callback + */ virtual void socket_attach_recv(void *handle, void (*callback)(void *), void *id) = 0; }; diff --git a/net/NetworkSocketAPI/Socket.h b/net/NetworkSocketAPI/Socket.h index 6fb8d6127f..cb359e7040 100644 --- a/net/NetworkSocketAPI/Socket.h +++ b/net/NetworkSocketAPI/Socket.h @@ -29,34 +29,34 @@ public: virtual ~Socket(); /** Set blocking or non-blocking mode of the socket - \param blocking true for blocking mode, false for non-blocking mode. - */ + * @param blocking true for blocking mode, false for non-blocking mode. + */ void set_blocking(bool blocking); /** Set timeout on a socket operation if blocking behaviour is enabled - \param timeout timeout in ms - */ + * @param timeout timeout in ms + */ void set_timeout(unsigned int timeout); - /** Set socket options - \param optname Option ID - \param optval Option value - \param optlen Length of the option value - \return 0 on success, negative on failure - */ + /* Set socket options + * @param optname Option ID + * @param optval Option value + * @param optlen Length of the option value + * @return 0 on success, negative on failure + */ int set_option(int optname, const void *optval, unsigned optlen); - /** Get socket options - \param optname Option ID - \param optval Buffer pointer where to write the option value - \param optlen Length of the option value - \return 0 on success, negative on failure - */ + /* Get socket options + * @param optname Option ID + * @param optval Buffer pointer where to write the option value + * @param optlen Length of the option value + * @return 0 on success, negative on failure + */ int get_option(int optname, void *optval, unsigned *optlen); /** Close the socket - \param shutdown free the left-over data in message queues - */ + * @param shutdown free the left-over data in message queues + */ int close(bool shutdown=true); protected: diff --git a/net/NetworkSocketAPI/SocketAddress.h b/net/NetworkSocketAPI/SocketAddress.h index e6fedc2496..44e55bc9d1 100644 --- a/net/NetworkSocketAPI/SocketAddress.h +++ b/net/NetworkSocketAPI/SocketAddress.h @@ -36,42 +36,42 @@ class NetworkInterface; class SocketAddress { public: /** SocketAddress construction using DNS resolution - /param iface NetworkInterface to use for DNS resolution - /param addr Null-terminated hostname that will be resolved - /param port 16-bit port - /note on failure, IP address and port will be set to null - */ + * @param iface NetworkInterface to use for DNS resolution + * @param addr Null-terminated hostname that will be resolved + * @param port 16-bit port + * @note on failure, IP address and port will be set to null + */ SocketAddress(NetworkInterface *iface, const char *addr, uint16_t port = 0); /** SocketAddress construction - /param addr Null-terminated IP address - /param port 16-bit port - /note on failure, IP address and port will be set to null - */ + * @param addr Null-terminated IP address + * @param port 16-bit port + * @note on failure, IP address and port will be set to null + */ SocketAddress(const char *addr = 0, uint16_t port = 0); /** SocketAddress construction - /param addr SocketAddress to copy - */ + * @param addr SocketAddress to copy + */ SocketAddress(const SocketAddress &addr); /** Set the IP address - \param addr Null-terminated string representing the IP address + * @param addr Null-terminated string representing the IP address */ void set_ip_address(const char *addr); /** Set the port - \param port 16-bit port + * @param port 16-bit port */ void set_port(uint16_t port); /** Get the IP address - \return The string representation of the IP Address + * @return The string representation of the IP Address */ const char *get_ip_address() const; /** Get the port - \return The 16-bit port + * @return The 16-bit port */ uint16_t get_port(void) const; diff --git a/net/NetworkSocketAPI/TCPServer.h b/net/NetworkSocketAPI/TCPServer.h index 697104c66f..0072ec3f1c 100644 --- a/net/NetworkSocketAPI/TCPServer.h +++ b/net/NetworkSocketAPI/TCPServer.h @@ -26,33 +26,33 @@ class TCPServer : public Socket { public: /** TCP Server lifetime - */ + */ TCPServer(NetworkInterface *iface); virtual ~TCPServer(); /** Bind a socket to a specific port - \param port The port to listen for incoming connections on - \return 0 on success, negative on failure - */ + * @param port The port to listen for incoming connections on + * @return 0 on success, negative on failure + */ int bind(uint16_t port); /** Start listening for incoming connections - \param backlog Number of pending connections that can be queued up at any - one time [Default: 1] - \return 0 on success, negative on failure - */ + * @param backlog Number of pending connections that can be queued up at any + * one time [Default: 1] + * @return 0 on success, negative on failure + */ int listen(int backlog=1); /** Accept a new connection. - \param socket A TCPSocket instance that will handle the incoming connection. - \return 0 on success, negative on failure. - */ + * @param socket A TCPSocket instance that will handle the incoming connection. + * @return 0 on success, negative on failure. + */ int accept(TCPSocket *connection); /** Register a callback on when a new connection is ready - \param callback Function to call when accept will succeed, may be called in - interrupt context. - */ + * @param callback Function to call when accept will succeed, may be called in + * interrupt context. + */ void attach_accept(FunctionPointer callback); template diff --git a/net/NetworkSocketAPI/TCPSocket.h b/net/NetworkSocketAPI/TCPSocket.h index 36693c387f..b4f7917424 100644 --- a/net/NetworkSocketAPI/TCPSocket.h +++ b/net/NetworkSocketAPI/TCPSocket.h @@ -20,53 +20,52 @@ #include "Socket.h" #include "NetworkInterface.h" -/** -TCP socket connection -*/ +/** TCP socket connection + */ class TCPSocket : public Socket { public: /** TCP socket lifetime - */ + */ TCPSocket(NetworkInterface *iface); virtual ~TCPSocket(); /** Connects this TCP socket to the server - \param host The host to connect to. It can either be an IP Address - or a hostname that will be resolved with DNS - \param port The host's port to connect to - \return 0 on success, negative on failure - */ + * @param host The host to connect to. It can either be an IP Address + * or a hostname that will be resolved with DNS + * @param port The host's port to connect to + * @return 0 on success, negative on failure + */ int connect(const char *host, uint16_t port); /** Connects this TCP socket to the server - \param address SocketAddress to connect to - \return 0 on success, negative on failure - */ + * @param address SocketAddress to connect to + * @return 0 on success, negative on failure + */ int connect(const SocketAddress &address); /** Check if the socket is connected - \return true if connected, false otherwise - */ + * @return true if connected, false otherwise + */ bool is_connected(); /** Send data to the remote host - \param data The buffer to send to the host - \param size The length of the buffer to send - \return Number of written bytes on success, negative on failure - */ + * @param data The buffer to send to the host + * @param size The length of the buffer to send + * @return Number of written bytes on success, negative on failure + */ int send(const void *data, unsigned size); /** Receive data from the remote host - \param data The buffer in which to store the data received from the host - \param size The maximum length of the buffer - \return Number of received bytes on success, negative on failure - */ + * @param data The buffer in which to store the data received from the host + * @param size The maximum length of the buffer + * @return Number of received bytes on success, negative on failure + */ int recv(void *data, unsigned size); /** Register a callback on when send is ready - \param callback Function to call when send will succeed, may be called in - interrupt context. - */ + * @param callback Function to call when send will succeed, may be called in + * interrupt context. + */ void attach_send(FunctionPointer callback); template @@ -75,9 +74,9 @@ public: } /** Register a callback on when recv is ready - \param callback Function to call when recv will succeed, may be called in - interrupt context. - */ + * @param callback Function to call when recv will succeed, may be called in + * interrupt context. + */ void attach_recv(FunctionPointer callback); template diff --git a/net/NetworkSocketAPI/UDPSocket.h b/net/NetworkSocketAPI/UDPSocket.h index 9d1ab06112..1614f8f920 100644 --- a/net/NetworkSocketAPI/UDPSocket.h +++ b/net/NetworkSocketAPI/UDPSocket.h @@ -20,44 +20,43 @@ #include "Socket.h" #include "NetworkInterface.h" -/** -UDP Socket -*/ +/** UDP Socket + */ class UDPSocket : public Socket { public: /** UDPSocket lifetime - */ + */ UDPSocket(NetworkInterface *iface); virtual ~UDPSocket(); /** Bind a UDP Server Socket to a specific port - \param port The port to listen for incoming connections on - \return 0 on success, negative on failure. - */ + * @param port The port to listen for incoming connections on + * @return 0 on success, negative on failure. + */ int bind(uint16_t port); /** Send a packet to a remote endpoint - \param address The remote SocketAddress - \param data The packet to be sent - \param size The length of the packet to be sent - \return the number of written bytes on success, negative on failure - */ + * @param address The remote SocketAddress + * @param data The packet to be sent + * @param size The length of the packet to be sent + * @return The number of written bytes on success, negative on failure + */ int sendto(const SocketAddress &address, const void *data, unsigned size); /** Receive a packet from a remote endpoint - \param address Destination for the remote SocketAddress or null - \param buffer The buffer for storing the incoming packet data - If a packet is too long to fit in the supplied buffer, - excess bytes are discarded - \param size The length of the buffer - \return the number of received bytes on success, negative on failure - */ + * @param address Destination for the remote SocketAddress or null + * @param buffer The buffer for storing the incoming packet data + * If a packet is too long to fit in the supplied buffer, + * excess bytes are discarded + * @param size The length of the buffer + * @return The number of received bytes on success, negative on failure + */ int recvfrom(SocketAddress *address, void *buffer, unsigned size); /** Register a callback on when send is ready - \param callback Function to call when send will succeed, may be called in - interrupt context. - */ + * @param callback Function to call when send will succeed, may be called in + * interrupt context. + */ void attach_send(FunctionPointer callback); template @@ -66,9 +65,9 @@ public: } /** Register a callback on when recv is ready - \param callback Function to call when recv will succeed, may be called in - interrupt context. - */ + * @param callback Function to call when recv will succeed, may be called in + * interrupt context. + */ void attach_recv(FunctionPointer callback); template diff --git a/net/NetworkSocketAPI/WiFiInterface.h b/net/NetworkSocketAPI/WiFiInterface.h index 541a6a8fa8..21fa397a66 100644 --- a/net/NetworkSocketAPI/WiFiInterface.h +++ b/net/NetworkSocketAPI/WiFiInterface.h @@ -20,7 +20,7 @@ #include "NetworkInterface.h" /** Enum for WiFi encryption types -*/ + */ enum nsapi_security_t { NSAPI_SECURITY_NONE = 0, /*!< open access point */ NSAPI_SECURITY_WEP, /*!< phrase conforms to WEP */ @@ -35,16 +35,16 @@ class WiFiInterface : public NetworkInterface { public: /** Start the interface - /param ssid Name of the network to connect to - /param pass Security passphrase to connect to the network - /param security Type of encryption for connection - /return 0 on success, negative on failure - */ + * @param ssid Name of the network to connect to + * @param pass Security passphrase to connect to the network + * @param security Type of encryption for connection + * @return 0 on success, negative on failure + */ virtual int connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE) = 0; /** Stop the interface - /return 0 on success, negative on failure - */ + * @return 0 on success, negative on failure + */ virtual int disconnect() = 0; };