Corrections from review meeting

-Rename get_latency_estimate_to_address, use rtt instead of latency
-Update descriptions of added methods

Author: Arto Kinnunen

features/netsocket/InternetSocket.cpp

@@ -114,13 +114,13 @@ int InternetSocket::leave_multicast_group(const SocketAddress &address)
     return modify_multicast_group(address, NSAPI_DROP_MEMBERSHIP);
 }
 
-int InternetSocket::get_latency_estimate_to_address(const SocketAddress &address, uint32_t *latency)
+int InternetSocket::get_rtt_estimate_to_address(const SocketAddress &address, uint32_t *rtt_estimate)
 {
     nsapi_error_t ret;
     nsapi_latency_req_t ns_api_latency_req;
     unsigned opt_len = sizeof(nsapi_latency_req_t);
 
-    if (!latency) {
+    if (!rtt_estimate) {
         return NSAPI_ERROR_PARAMETER;
     }
 
@@ -129,8 +129,8 @@ int InternetSocket::get_latency_estimate_to_address(const SocketAddress &address
 
     ret = this->getsockopt(NSAPI_SOCKET, NSAPI_LATENCY, (void *)&ns_api_latency_req, &opt_len);
     if (ret == NSAPI_ERROR_OK) {
-        // success, latency found
-        *latency = ns_api_latency_req.latency;
+        // success, latency found. Convert to RTT.
+        *rtt_estimate = ns_api_latency_req.latency * 2;
     }
 
     return ret;

features/netsocket/InternetSocket.h

@@ -86,23 +86,30 @@ class InternetSocket : public Socket {
      */
     int leave_multicast_group(const SocketAddress &address);
 
-    /** Get estimated latency to reach destination address.
+    /** Get estimated round trip time to destination address.
      *
-     * @param address   Destination address to estimate latency.
-     * @param latency   Returned latency value in milliseconds.
+     * Use estimated round trip time to adjust application retry timers to work in networks
+     * that have low data rate and high latency.
+     *
+     * @param address   Destination address to use in rtt estimate.
+     * @param rtt_estimate   Returned round trip time value in milliseconds.
      *  @return         NSAPI_ERROR_OK on success.
      *  @return         NSAPI_ERROR_PARAMETER if the provided pointer is invalid.
      *  @return         negative error code on other failures (@see InternetSocket::getsockopt).
      */
-    int get_latency_estimate_to_address(const SocketAddress &address, uint32_t *latency);
+    int get_rtt_estimate_to_address(const SocketAddress &address, uint32_t *rtt_estimate);
 
-    /** Get estimated stagger value to reach destination address.
+    /** Get estimated stagger value.
+     *
+     * Stagger value is a time that application should wait before using heavy network operations after connecting to network.
+     * Purpose of staggering is to avoid network congestion that may happen in low bandwith networks if multiple
+     * applications simultaneously start heavy network usage after joining to the network.
      *
-     * @param address       Address to estimate stagger values.
+     * @param address       Destination added used to estimate stagger value.
      * @param data_amount   Amount of bytes to transfer in kilobytes.
      * @param stagger_min   Minimum stagger value in seconds.
      * @param stagger_max   Maximum stagger value in seconds.
-     * @param stagger_rand  Randomized stagger value in seconds.
+     * @param stagger_rand  Randomized stagger value between stagger_min and stagger_max in seconds.
      * @return              NSAPI_ERROR_OK on success.
      * @return              negative error code on other failures (@see InternetSocket::getsockopt).
      */