docs(iot): revamp (#3068)

Co-authored-by: Rémy Léone <rleone@scaleway.com>

Author: scaleway-bot

cmd/scw/testdata/test-all-usage-iot-device-get-metrics-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a device's metrics.
+Get the metrics of an existing device, specified by its device ID.
 
 USAGE:
   scw iot device get-metrics <device-id ...> [arg=value ...]

cmd/scw/testdata/test-all-usage-iot-network-create-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a new Network.
+Create a new network for an existing hub.  Beside the default network, you can add networks for different data providers. Possible network types are Sigfox and REST.
 
 USAGE:
   scw iot network create [arg=value ...]

cmd/scw/testdata/test-all-usage-iot-network-delete-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a Network.
+Delete an existing network, specified by its network ID. Deleting a network is permanent, and cannot be undone.
 
 USAGE:
   scw iot network delete <network-id ...> [arg=value ...]

cmd/scw/testdata/test-all-usage-iot-network-get-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Retrieve a specific Network.
+Retrieve an existing network, specified by its network ID.  The response returns full details of the network, including its type, the topic prefix and its endpoint.
 
 USAGE:
   scw iot network get <network-id ...> [arg=value ...]

cmd/scw/testdata/test-all-usage-iot-network-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List the Networks.
+List the networks.
 
 USAGE:
   scw iot network list [arg=value ...]

cmd/scw/testdata/test-all-usage-iot-network-usage.golden

@@ -6,10 +6,10 @@ USAGE:
   scw iot network <command>
 
 AVAILABLE COMMANDS:
-  create      Create a new Network
+  create      Create a new network
   delete      Delete a Network
-  get         Retrieve a specific Network
-  list        List the Networks
+  get         Retrieve a specific network
+  list        List the networks
 
 FLAGS:
   -h, --help   help for network

cmd/scw/testdata/test-all-usage-iot-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-IoT API.
+IoT Hub API.
 
 USAGE:
   scw iot <command>

docs/commands/iot.md

@@ -1,6 +1,6 @@
 <!-- DO NOT EDIT: this file is automatically generated using scw-doc-gen -->
 # Documentation for `scw iot`
-IoT API.
+IoT Hub API.
 
 - [IoT Device commands](#iot-device-commands)
   - [Add a device](#add-a-device)
@@ -25,10 +25,10 @@ IoT API.
   - [Set the certificate authority of a hub](#set-the-certificate-authority-of-a-hub)
   - [Update a hub](#update-a-hub)
 - [IoT Network commands](#iot-network-commands)
-  - [Create a new Network](#create-a-new-network)
+  - [Create a new network](#create-a-new-network)
   - [Delete a Network](#delete-a-network)
-  - [Retrieve a specific Network](#retrieve-a-specific-network)
-  - [List the Networks](#list-the-networks)
+  - [Retrieve a specific network](#retrieve-a-specific-network)
+  - [List the networks](#list-the-networks)
 - [IoT Route commands](#iot-route-commands)
   - [Create a route](#create-a-route)
   - [Delete a route](#delete-a-route)
@@ -172,7 +172,7 @@ scw iot device get-certificate <device-id ...> [arg=value ...]
 
 ### Get a device's metrics
 
-Get a device's metrics.
+Get the metrics of an existing device, specified by its device ID.
 
 **Usage:**
 
@@ -491,9 +491,9 @@ scw iot hub update <hub-id ...> [arg=value ...]
 IoT Network commands.
 
 
-### Create a new Network
+### Create a new network
 
-Create a new Network.
+Create a new network for an existing hub.  Beside the default network, you can add networks for different data providers. Possible network types are Sigfox and REST.
 
 **Usage:**
 
@@ -516,7 +516,7 @@ scw iot network create [arg=value ...]
 
 ### Delete a Network
 
-Delete a Network.
+Delete an existing network, specified by its network ID. Deleting a network is permanent, and cannot be undone.
 
 **Usage:**
 
@@ -534,9 +534,9 @@ scw iot network delete <network-id ...> [arg=value ...]
 
 
 
-### Retrieve a specific Network
+### Retrieve a specific network
 
-Retrieve a specific Network.
+Retrieve an existing network, specified by its network ID.  The response returns full details of the network, including its type, the topic prefix and its endpoint.
 
 **Usage:**
 
@@ -554,9 +554,9 @@ scw iot network get <network-id ...> [arg=value ...]
 
 
 
-### List the Networks
+### List the networks
 
-List the Networks.
+List the networks.
 
 **Usage:**
 

internal/namespaces/iot/v1/iot_cli.go

@@ -58,7 +58,7 @@ func GetGeneratedCommands() *core.Commands {
 func iotRoot() *core.Command {
 	return &core.Command{
 		Short:     `This API allows you to manage IoT hubs and devices`,
-		Long:      `IoT API.`,
+		Long:      `IoT Hub API.`,
 		Namespace: "iot",
 	}
 }
@@ -1056,7 +1056,7 @@ func iotDeviceDelete() *core.Command {
 func iotDeviceGetMetrics() *core.Command {
 	return &core.Command{
 		Short:     `Get a device's metrics`,
-		Long:      `Get a device's metrics.`,
+		Long:      `Get the metrics of an existing device, specified by its device ID.`,
 		Namespace: "iot",
 		Resource:  "device",
 		Verb:      "get-metrics",
@@ -1504,8 +1504,8 @@ func iotRouteDelete() *core.Command {
 
 func iotNetworkList() *core.Command {
 	return &core.Command{
-		Short:     `List the Networks`,
-		Long:      `List the Networks.`,
+		Short:     `List the networks`,
+		Long:      `List the networks.`,
 		Namespace: "iot",
 		Resource:  "network",
 		Verb:      "list",
@@ -1588,8 +1588,8 @@ func iotNetworkList() *core.Command {
 
 func iotNetworkCreate() *core.Command {
 	return &core.Command{
-		Short:     `Create a new Network`,
-		Long:      `Create a new Network.`,
+		Short:     `Create a new network`,
+		Long:      `Create a new network for an existing hub.  Beside the default network, you can add networks for different data providers. Possible network types are Sigfox and REST.`,
 		Namespace: "iot",
 		Resource:  "network",
 		Verb:      "create",
@@ -1641,8 +1641,8 @@ func iotNetworkCreate() *core.Command {
 
 func iotNetworkGet() *core.Command {
 	return &core.Command{
-		Short:     `Retrieve a specific Network`,
-		Long:      `Retrieve a specific Network.`,
+		Short:     `Retrieve a specific network`,
+		Long:      `Retrieve an existing network, specified by its network ID.  The response returns full details of the network, including its type, the topic prefix and its endpoint.`,
 		Namespace: "iot",
 		Resource:  "network",
 		Verb:      "get",
@@ -1672,7 +1672,7 @@ func iotNetworkGet() *core.Command {
 func iotNetworkDelete() *core.Command {
 	return &core.Command{
 		Short:     `Delete a Network`,
-		Long:      `Delete a Network.`,
+		Long:      `Delete an existing network, specified by its network ID. Deleting a network is permanent, and cannot be undone.`,
 		Namespace: "iot",
 		Resource:  "network",
 		Verb:      "delete",