From 501f5ae32c9bf8df364ce04943754b010ce5df2a Mon Sep 17 00:00:00 2001
From: Seppo Takalo <seppo.takalo@arm.com>
Date: Thu, 10 Jan 2019 12:01:39 +0200
Subject: [PATCH] Add more documentation to Socket classes.

---
 features/netsocket/DNS.h               |  2 ++
 features/netsocket/DTLSSocket.h        |  5 ++++-
 features/netsocket/DTLSSocketWrapper.h |  2 +-
 features/netsocket/Socket.h            | 11 ++++++++++-
 features/netsocket/TLSSocket.h         |  4 ++++
 features/netsocket/TLSSocketWrapper.h  |  6 +++++-
 6 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/features/netsocket/DNS.h b/features/netsocket/DNS.h
index 3570cdc6a7..a9aa5c0a48 100644
--- a/features/netsocket/DNS.h
+++ b/features/netsocket/DNS.h
@@ -100,3 +100,5 @@ public:
 };
 
 #endif
+
+/** @} */
\ No newline at end of file
diff --git a/features/netsocket/DTLSSocket.h b/features/netsocket/DTLSSocket.h
index 460f530398..c43ecabe52 100644
--- a/features/netsocket/DTLSSocket.h
+++ b/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 {
diff --git a/features/netsocket/DTLSSocketWrapper.h b/features/netsocket/DTLSSocketWrapper.h
index a0060590da..1d024682b5 100644
--- a/features/netsocket/DTLSSocketWrapper.h
+++ b/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:
diff --git a/features/netsocket/Socket.h b/features/netsocket/Socket.h
index 1906b034ef..7a9c53407e 100644
--- a/features/netsocket/Socket.h
+++ b/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:
diff --git a/features/netsocket/TLSSocket.h b/features/netsocket/TLSSocket.h
index ccb6c69ea8..0630d2c156 100644
--- a/features/netsocket/TLSSocket.h
+++ b/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:
diff --git a/features/netsocket/TLSSocketWrapper.h b/features/netsocket/TLSSocketWrapper.h
index 5d0fc44c74..1adb793a33 100644
--- a/features/netsocket/TLSSocketWrapper.h
+++ b/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: