Add more documentation to Socket classes.

Author: Seppo Takalo

features/netsocket/DNS.h

@@ -100,3 +100,5 @@ class DNS {
 };
 
 #endif
+
+/** @} */

features/netsocket/DTLSSocket.h

@@ -30,7 +30,10 @@
 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
 
 /**
- * \brief DTLSSocket implement DTLS stream over the existing Socket transport
+ * \brief DTLSSocket implement DTLS stream over UDP Socket.
+ *
+ * This is a easy to use helper class that uses DTLSSocketWrapper with
+ * internal UDPSocket.
  */
 
 class DTLSSocket : public DTLSSocketWrapper {

features/netsocket/DTLSSocketWrapper.h

@@ -28,7 +28,7 @@
 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
 
 /**
- * \brief DTLSSocketWrapper implement DTLS stream over the existing Socket transport
+ * \brief DTLSSocketWrapper implement DTLS stream over the existing Socket transport.
  */
 class DTLSSocketWrapper : public TLSSocketWrapper {
 public:

features/netsocket/Socket.h

@@ -25,7 +25,16 @@
 #include "netsocket/SocketAddress.h"
 #include "Callback.h"
 
-/** Abstract socket class
+/** Socket interface.
+ *
+ * This class defines the Mbed OS Socket API.
+ * Socket is an abstract interface for communicating to remote endpoints.
+ *
+ * This API is intented to use for applications and libraries instead of
+ * using some protocol specific implementation of it. For example TCPSocket
+ * and UDPSocket are implementations of Socket interface.
+ * Socket API is intentionally not protocol specific and allows all protocol
+ * to provide same API regardless of underlying transport mechanism.
  */
 class Socket {
 public:

features/netsocket/TLSSocket.h

@@ -36,6 +36,10 @@
 
 /**
  * \brief TLSSocket a wrapper around TCPSocket for interacting with TLS servers.
+ *
+ * TLSSocket uses the TLSSocketWrapper with internal TCP socket. This is a
+ * easy to use helper for creating commonly used TLS connection over TCP.
+ *
  */
 class TLSSocket : public TLSSocketWrapper {
 public:

features/netsocket/TLSSocketWrapper.h

@@ -35,7 +35,11 @@
 #if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
 
 /**
- * \brief TLSSocket a wrapper around Socket for interacting with TLS servers
+ * TLSSocket a wrapper around Socket for interacting with TLS servers.
+ *
+ * TLSSocketWrapper can use any Socket as a transport and after
+ * completing the TLS handshake, can be used as any Socket would be used.
+ *
  */
 class TLSSocketWrapper : public Socket {
 public: