Doxygen corrections to DTLSSocket.h, TLSSocket.h, TLSSocketWrapper.h

and DTLSSocketWrapper.h

Author: KariHaapalehto

features/netsocket/DTLSSocket.h

@@ -29,26 +29,31 @@
 // This class requires Mbed TLS SSL/TLS client code
 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
 
+/**
+ * \brief DTLSSocket implement DTLS stream over the existing Socket transport
+ */
+
 class DTLSSocket : public DTLSSocketWrapper {
 public:
-    /** Create an uninitialized DTLS socket
+    /** Create an uninitialized DTLS socket.
      *
      *  Must call open to initialize the socket on a network stack.
+     *  @param _udp_socket    Underlying transport socket.
      */
     DTLSSocket() : DTLSSocketWrapper(&_udp_socket) {}
 
     /** Destroy the DTLSSocket and closes the transport.
      */
     virtual ~DTLSSocket();
 
-    /** Create a socket on a network interface
+    /** Create a socket on a network interface.
      *
      *  Creates and opens a socket on the network stack of the given
      *  network interface.
      *  If hostname is also given, user is not required to call set_hostname() later.
      *
-     *  @param stack    Network stack as target for socket
-     *  @param hostname Hostname used for certificate verification
+     *  @param stack    Network stack as target for socket.
+     *  @param hostname Hostname used for certificate verification.
      */
     template <typename S>
     DTLSSocket(S *stack, const char *hostname = NULL) : DTLSSocketWrapper(&_udp_socket, hostname)
@@ -57,14 +62,14 @@ class DTLSSocket : public DTLSSocketWrapper {
         MBED_ASSERT(ret == NSAPI_ERROR_OK);
     }
 
-    /** Opens a socket
+    /** Opens a socket.
      *
      *  Creates a network socket on the network stack of the given
      *  network interface. Not needed if stack is passed to the
      *  socket's constructor.
      *
-     *  @param stack    Network stack as target for socket
-     *  @return         0 on success, negative error code on failure
+     *  @param stack    Network stack as target for socket.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual nsapi_error_t open(NetworkStack *stack)
     {
@@ -79,14 +84,14 @@ class DTLSSocket : public DTLSSocketWrapper {
 
     using DTLSSocketWrapper::connect;
 
-    /** Connects TCP socket to a remote host
+    /** Connects TCP socket to a remote host.
      *
      *  Initiates a connection to a remote server specified by either
      *  a domain name or an IP address and a port.
      *
-     *  @param host     Hostname of the remote host
-     *  @param port     Port of the remote host
-     *  @return         0 on success, negative error code on failure
+     *  @param host     Hostname of the remote host.
+     *  @param port     Port of the remote host.
+     *  @return         0 on success, negative error code on failure.
      */
     nsapi_error_t connect(const char *host, uint16_t port);
 

features/netsocket/DTLSSocketWrapper.h

@@ -1,3 +1,4 @@
+/** @file DTLSSocketWrapper.h DTLSSocketWrapper */
 /*
  * Copyright (c) 2018 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
@@ -14,6 +15,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @addtogroup netsocket
+* @{
+*/
 
 #ifndef DTLSSOCKETWRAPPER_H
 #define DTLSSOCKETWRAPPER_H
@@ -23,8 +27,17 @@
 // This class requires Mbed TLS SSL/TLS client code
 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
 
+/**
+ * \brief DTLSSocketWrapper implement DTLS stream over the existing Socket transport
+ */
 class DTLSSocketWrapper : public TLSSocketWrapper {
 public:
+    /** Create a DTLSSocketWrapper.
+     *
+     * @param transport    Underlying transport socket to wrap.
+     * @param hostname     Hostname of the remote host, used for certificate checking.
+     * @param control      Transport control mode. See @ref control_transport.
+     */
     DTLSSocketWrapper(Socket *transport, const char *hostname = NULL, control_transport control = TRANSPORT_CONNECT_AND_CLOSE);
 private:
     static void timing_set_delay(void *ctx, uint32_t int_ms, uint32_t fin_ms);
@@ -37,3 +50,4 @@ class DTLSSocketWrapper : public TLSSocketWrapper {
 
 #endif
 #endif
+/** @} */

features/netsocket/TLSSocket.h

@@ -35,31 +35,31 @@
 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
 
 /**
- * \brief TLSSocket a wrapper around TCPSocket for interacting with TLS servers
+ * \brief TLSSocket a wrapper around TCPSocket for interacting with TLS servers.
  */
 class TLSSocket : public TLSSocketWrapper {
 public:
-    /** Create an uninitialized socket
+    /** Create an uninitialized socket.
      *
      *  Must call open to initialize the socket on a network stack.
+     *  @param tcp_socket    Underlying transport socket.
      */
     TLSSocket() : TLSSocketWrapper(&tcp_socket) {}
 
     /** Destroy the TLSSocket and closes the transport.
      */
     virtual ~TLSSocket();
 
-    /** Opens a socket
+    /** Opens a socket.
      *
      *  Creates a network socket on the network stack of the given
-     *  network interface. Not needed if stack is passed to the
-     *  socket's constructor.
+     *  network interface. 
      *
      *  @note TLSSocket cannot be reopened after closing. It should be destructed to
      *        clear internal TLS memory structures.
      *
-     *  @param stack    Network stack as target for socket
-     *  @return         0 on success, negative error code on failure
+     *  @param stack    Network stack as target for socket.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual nsapi_error_t open(NetworkStack *stack)
     {
@@ -74,14 +74,14 @@ class TLSSocket : public TLSSocketWrapper {
 
     using TLSSocketWrapper::connect;
 
-    /** Connects TCP socket to a remote host
+    /** Connects TCP socket to a remote host.
      *
      *  Initiates a connection to a remote server specified by either
      *  a domain name or an IP address and a port.
      *
-     *  @param host     Hostname of the remote host
-     *  @param port     Port of the remote host
-     *  @return         0 on success, negative error code on failure
+     *  @param host     Hostname of the remote host.
+     *  @param port     Port of the remote host.
+     *  @return         0 on success, negative error code on failure.
      */
     nsapi_error_t connect(const char *host, uint16_t port);
 

features/netsocket/TLSSocketWrapper.h

@@ -39,23 +39,25 @@
  */
 class TLSSocketWrapper : public Socket {
 public:
+    /** Transport modes */
     enum control_transport {
-        TRANSPORT_KEEP,
-        TRANSPORT_CONNECT_AND_CLOSE,
-        TRANSPORT_CONNECT,
-        TRANSPORT_CLOSE,
+        TRANSPORT_KEEP,                 /**< Doesn't call connect() or close() on transport socket */
+        TRANSPORT_CONNECT_AND_CLOSE,    /**< Does call connect() and close() on transport socket */
+        TRANSPORT_CONNECT,              /**< Does call only connect() on transport socket */
+        TRANSPORT_CLOSE,                /**< Does call close() on transport socket */
     };
 
-    /* Create a TLSSocketWrapper
+    /** Create a TLSSocketWrapper.
      *
-     * @param transport    Underlying transport socket to wrap
-     * @param hostname     Hostname of the remote host, used for certificate checking
+     * @param transport    Underlying transport socket to wrap.
+     * @param hostname     Hostname of the remote host, used for certificate checking.
+     * @param control      Transport control mode. See @ref control_transport.
      */
     TLSSocketWrapper(Socket *transport, const char *hostname = NULL, control_transport control = TRANSPORT_CONNECT_AND_CLOSE);
 
-    /** Destroy a socket wrapper
+    /** Destroy a socket wrapper.
      *
-     *  Closes socket wrapper if the socket wrapper is still open
+     *  Closes socket wrapper if the socket wrapper is still open.
      */
     virtual ~TLSSocketWrapper();
 
@@ -64,28 +66,33 @@ class TLSSocketWrapper : public Socket {
      * TLSSocket requires hostname that is used to verify the certificate.
      * If hostname is not given in constructor, this function must be used before
      * starting the TLS handshake.
+     *
+     * @param hostname     Hostname of the remote host, used for certificate checking.
      */
     void set_hostname(const char *hostname);
 
     /** Sets the certification of Root CA.
      *
      * @param root_ca Root CA Certificate in any mbed-TLS supported format.
      * @param len     Length of certificate (including terminating 0 for PEM).
+     * @return        0 on success, negative error code on failure.
      */
     nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
 
     /** Sets the certification of Root CA.
      *
-     * @param root_ca_pem Root CA Certificate in PEM format
+     * @param root_ca_pem Root CA Certificate in PEM format.
+     * @return            0 on success, negative error code on failure.
      */
     nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
 
     /** Sets client certificate, and client private key.
      *
      * @param client_cert client certification in PEM or DER format.
      * @param client_cert_len certificate size including the terminating null byte for PEM data.
-     * @param client_private_key_pem client private key in PEM or DER format
+     * @param client_private_key_pem client private key in PEM or DER format.
      * @param client_private_key_len key size including the terminating null byte for PEM data
+     * @return   0 on success, negative error code on failure.
      */
     nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
                                       const void *client_private_key_pem, size_t client_private_key_len);
@@ -94,6 +101,7 @@ class TLSSocketWrapper : public Socket {
      *
      * @param client_cert_pem Client certification in PEM format.
      * @param client_private_key_pem Client private key in PEM format.
+     * @return   0 on success, negative error code on failure.
      */
     nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
 
@@ -102,20 +110,19 @@ class TLSSocketWrapper : public Socket {
      *  The socket must be connected to a remote host. Returns the number of
      *  bytes sent from the buffer.
      *
-     *  @param data     Buffer of data to send to the host
-     *  @param size     Size of the buffer in bytes
-     *  @return         Number of sent bytes on success, negative error
-     *                  code on failure
+     *  @param data     Buffer of data to send to the host.
+     *  @param size     Size of the buffer in bytes.
+     *  @return         Number of sent bytes on success, negative error code on failure.
      */
     virtual nsapi_error_t send(const void *data, nsapi_size_t size);
 
-    /** Receive data over a TLS socket
+    /** Receive data over a TLS socket.
      *
      *  The socket must be connected to a remote host. Returns the number of
      *  bytes received into the buffer.
      *
-     *  @param data     Destination buffer for data received from the host
-     *  @param size     Size of the buffer in bytes
+     *  @param data     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. If no data is available to be received
      *                  and the peer has performed an orderly shutdown,
@@ -140,48 +147,55 @@ class TLSSocketWrapper : public Socket {
     virtual nsapi_error_t getpeername(SocketAddress *address);
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C) || defined(DOXYGEN_ONLY)
-    /** Get own certificate directly from Mbed TLS
-     * @return internal Mbed TLS X509 structure
+    /** Get own certificate directly from Mbed TLS.
+     *
+     * @return internal Mbed TLS X509 structure.
      */
     mbedtls_x509_crt *get_own_cert();
 
-    /** Set own certificate directly to Mbed TLS
+    /** Set own certificate directly to Mbed TLS.
+     *
      * @param crt Mbed TLS X509 certificate chain.
-     * @return error code from mbedtls_ssl_conf_own_cert()
+     * @return error code from mbedtls_ssl_conf_own_cert().
      */
     int set_own_cert(mbedtls_x509_crt *crt);
 
     /** Get CA chain structure.
+     *
      * @return Mbed TLS X509 certificate chain.
      */
     mbedtls_x509_crt *get_ca_chain();
 
-    /** Set CA chain directly to Mbed TLS
+    /** Set CA chain directly to Mbed TLS.
+     *
      * @param crt Mbed TLS X509 certificate chain.
      */
     void set_ca_chain(mbedtls_x509_crt *crt);
 #endif
 
-    /** Get internal Mbed TLS configuration structure
-     * @return Mbed TLS SSL config
+    /** Get internal Mbed TLS configuration structure.
+     *
+     * @return Mbed TLS SSL config.
      */
     mbedtls_ssl_config *get_ssl_config();
 
     /** Override Mbed TLS configuration.
-     * @param conf Mbed TLS SSL configuration structure
+     *
+     * @param conf Mbed TLS SSL configuration structure.
      */
     void set_ssl_config(mbedtls_ssl_config *conf);
 
     /** Get internal Mbed TLS context structure.
-     * @return SSL context
+     *
+     * @return SSL context.
      */
     mbedtls_ssl_context *get_ssl_context();
 
 protected:
-    /** Initiates TLS Handshake
+    /** Initiates TLS Handshake.
      *
-     *  Initiates a TLS handshake to a remote peer
-     *  Underlying transport socket should already be connected
+     *  Initiates a TLS handshake to a remote peer.
+     *  Underlying transport socket should already be connected.
      *
      *  Root CA certification must be set by set_ssl_ca_pem() before
      *  call this function.