Merge pull request #14443 from artokin/update_set_network_size_doc_515

[mbed-os-5.15] Improve WisunInterface set_network_size docs

Author: 0xc0170

features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h

@@ -169,24 +169,40 @@ class WisunInterface : public MeshInterfaceNanostack {
     /**
      * \brief Set Wi-SUN network size.
      *
-     * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
-     * If device is already connected to the Wi-SUN network then device will restart network discovery after
-     * changing the network size.
+     * Function stores network size parameter to the mbed-mesh-api and uses it when connect() is called for the next
+     * time. If a device is already connected to the Wi-SUN network, then the device will restart network discovery
+     * after changing the network size.
+     *
+     * It is recommended to set the correct network size because the Wi-SUN network configuration parameters are
+     * adjusted based on the selected network size. A network configured for a small amount of devices may not work
+     * optimally for large number of devices. This is because the network bandwidth is divided with all the devices in
+     * the network. Enough bandwidth must be reserved for application data usage as well as the Wi-SUN network
+     * operations. Application should adapt to the network characteristics by using the InternetSocket methods
+     * get_stagger_estimate_to_address and get_rtt_estimate_to_address.
+     *
+     * The network size is measured as hundreds of devices that are expected to join to the network. For example,
+     * for a 400-device network set network size to 4. The Wi-SUN stack will internally use one of the four possible
+     * configuration buckets based on the selected network size and data rate. The configuration buckets are defined
+     * for a small, medium, large and xlarge networks.
+     *
+     * For example, with 150kbs data rate set network size to:
+     * - 1 to use small configuration bucket.
+     * - 8 to use medium configuration bucket.
+     * - 15 to use large configuration bucket.
+     * - 25 to use xlarge configuration bucket.
+     *
+     * By default Wi-SUN stack is configured to use medium sized network.
      *
-     * Default value: medium
-     * Small network size: less than hundred devices
-     * Medium network size: hundreds of devices
-     * Large network size: thousands of devices
-     * Certificate: used on testing
+     * The network size should be set to 0 when running certification tests.
      *
-     * When network size is changed, it will override all or some of the following configuration values:
+     * When the network size is changed, it will override all or some of the following configuration values:
      * - Timing settings set by set_timing_parameters() of the Wi-SUN interface.
      * - RPL settings set by rpl_parameters_set() of the Border Router interface.
      *
-     * When network size is changed, and if timing or RPL values should be other than defaults set by stack for the network size,
-     * they need to set again using above function calls.
+     * When the network size is changed, and if timing or RPL values should be other than defaults set by stack for the
+     * network size, they need to set again using above function calls.
      *
-     * \param network_size Network size in hundreds of devices (e.g. 1200 devices is 12), 0x00 for network size certificate.
+     * \param network_size Network size in hundreds of devices (e.g. 12 for 1200 devices), 0 for certificate testing.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */

features/nanostack/mbed-mesh-api/mbed_lib.json

@@ -121,7 +121,7 @@
             "value": "\"Wi-SUN Network\""
         },
         "wisun-network-size": {
-            "help": "Expected amount of devices in the network as 100s of devices. with possible pre defined constants NETWORK_SIZE_SMALL, NETWORK_SIZE_MEDIUM, NETWORK_SIZE_LARGE, NETWORK_SIZE_XLARGE. if set to 0 Wi-SUN Certification configuration values are used. If don't define this(default null), then NETWORK_SIZE_MEDIUM will be used.",
+            "help": "Expected amount of devices in the network as hundreds of devices. Use any number or one of the predefined values NETWORK_SIZE_SMALL, NETWORK_SIZE_MEDIUM, NETWORK_SIZE_LARGE or NETWORK_SIZE_XLARGE. Set to 0 to use Wi-SUN Certification configuration values. If set to null, then NETWORK_SIZE_MEDIUM (meaning hundreds of devices in the network) will be used.",
             "value": null
         },
         "wisun-regulatory-domain": {
@@ -179,7 +179,7 @@
         "root-certificate-len": {
             "help": "Root certificate length; optional for PEM format, must be defined for DER format",
             "value": null
-        },        
+        },
         "own-certificate": {
             "help": "Own certificate; in PEM format must be a null terminated c-string, in DER format the own-certificate-len must be set",
             "value": null