docs(IoT): revamp api documentation (#3030)

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

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

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Add a device.
+Attach a device to a given Hub.
 
 USAGE:
   scw iot device create [arg=value ...]
 
 ARGS:
   name=<generated>                             Device name
-  hub-id                                       ID of the device's hub
-  [allow-insecure]                             Allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones
-  [allow-multiple-connections]                 Allow multiple physical devices to connect with this device's credentials
+  hub-id                                       Hub ID of the device
+  [allow-insecure]                             Defines whether to allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones
+  [allow-multiple-connections]                 Defines whether to allow multiple physical devices to connect with this device's credentials
   [message-filters.publish.policy]             How to use the topic list (unknown | accept | reject)
   [message-filters.publish.topics.{index}]     List of topics to accept or reject. It must be valid MQTT topics and up to 65535 characters
   [message-filters.subscribe.policy]           How to use the topic list (unknown | accept | reject)

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Remove a device.
+Remove a specific device from the specific Hub it is attached to.
 
 USAGE:
   scw iot device delete <device-id ...> [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Disable a device.
+Disable an existing device, specified by its device ID.
 
 USAGE:
   scw iot device disable <device-id ...> [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Enable a device.
+Enable a specific device, specified by its device ID.
 
 USAGE:
   scw iot device enable <device-id ...> [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a device's certificate.
+Get information for a particular PEM-encoded certificate, specified by the device ID. The response returns full details of the device, including its type of certificate.
 
 USAGE:
   scw iot device get-certificate <device-id ...> [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a device.
+Retrieve information about an existing device, specified by its device ID. Its full details, including name, status and ID, are returned in the response object.
 
 USAGE:
   scw iot device get <device-id ...> [arg=value ...]

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

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List devices.
+List all devices in the specified region. By default, returned devices are ordered by creation date in ascending order, though this can be modified via the `order_by` field.
 
 USAGE:
   scw iot device list [arg=value ...]
 
 ARGS:
   [order-by]         Ordering of requested devices (name_asc | name_desc | status_asc | status_desc | hub_id_asc | hub_id_desc | created_at_asc | created_at_desc | updated_at_asc | updated_at_desc | allow_insecure_asc | allow_insecure_desc)
-  [name]             Filter on the name
-  [hub-id]           Filter on the hub
-  [allow-insecure]   Filter on the allow_insecure flag
+  [name]             Name to filter for, only devices with this name will be returned
+  [hub-id]           Hub ID to filter for, only devices attached to this Hub will be returned
+  [allow-insecure]   Defines wheter to filter the allow_insecure flag
   [status]           Device status (enabled, disabled, etc.) (unknown | error | enabled | disabled)
   [region=fr-par]    Region to target. If none is passed will use default region from the config (fr-par | all)
 

cmd/scw/testdata/test-all-usage-iot-device-renew-certificate-usage.golden

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

cmd/scw/testdata/test-all-usage-iot-device-set-certificate-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Set a custom certificate on a device.
+Switch the existing certificate of a given device with an EM-encoded custom certificate.
 
 USAGE:
   scw iot device set-certificate <device-id ...> [arg=value ...]
 
 ARGS:
   device-id         Device ID
-  certificate-pem   The PEM-encoded custom certificate
+  certificate-pem   PEM-encoded custom certificate
   [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par)
 
 FLAGS:

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

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a device.
+Update the parameters of an existing device, specified by its device ID.
 
 USAGE:
   scw iot device update <device-id ...> [arg=value ...]
 
 ARGS:
   device-id                                    Device ID
-  [description]                                Device description
-  [allow-insecure]                             Allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones
-  [allow-multiple-connections]                 Allow multiple physical devices to connect with this device's credentials
+  [description]                                Description for the device
+  [allow-insecure]                             Defines whether to allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones
+  [allow-multiple-connections]                 Defines whether to allow multiple physical devices to connect with this device's credentials
   [message-filters.publish.policy]             How to use the topic list (unknown | accept | reject)
   [message-filters.publish.topics.{index}]     List of topics to accept or reject. It must be valid MQTT topics and up to 65535 characters
   [message-filters.subscribe.policy]           How to use the topic list (unknown | accept | reject)

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

@@ -1,16 +1,16 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a hub.
+Create a new Hub in the targeted region, specifying its configuration including name and product plan.
 
 USAGE:
   scw iot hub create [arg=value ...]
 
 ARGS:
   name=<generated>                   Hub name (up to 255 characters)
   [project-id]                       Project ID to use. If none is passed the default project ID will be used
-  product-plan=plan_shared           Hub feature set (plan_unknown | plan_shared | plan_dedicated | plan_ha)
+  product-plan=plan_shared           Hub product plan (plan_unknown | plan_shared | plan_dedicated | plan_ha)
   [disable-events]                   Disable Hub events
-  [events-topic-prefix]              Hub events topic prefix (default '$SCW/events')
+  [events-topic-prefix]              Topic prefix (default '$SCW/events') of Hub events
   [twins-graphite-config.push-uri]   
   [region=fr-par]                    Region to target. If none is passed will use default region from the config (fr-par)
 

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

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a hub.
+Delete an existing IoT Hub, specified by its Hub ID. Deleting a Hub is permanent, and cannot be undone.
 
 USAGE:
   scw iot hub delete <hub-id ...> [arg=value ...]
 
 ARGS:
   hub-id             Hub ID
-  [delete-devices]   Force deletion of devices added to this hub instead of rejecting operation
+  [delete-devices]   Defines whether to force the deletion of devices added to this Hub or reject the operation
   [region=fr-par]    Region to target. If none is passed will use default region from the config (fr-par)
 
 FLAGS:

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Disable a hub.
+Disable an existing IoT Hub, specified by its Hub ID.
 
 USAGE:
   scw iot hub disable <hub-id ...> [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Enable a hub.
+Enable an existing IoT Hub, specified by its Hub ID.
 
 USAGE:
   scw iot hub enable <hub-id ...> [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the certificate authority of a hub.
+Get information for a particular PEM-encoded certificate, specified by the Hub ID.
 
 USAGE:
   scw iot hub get-ca [arg=value ...]

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a hub.
+Retrieve information about an existing IoT Hub, specified by its Hub ID. Its full details, including name, status and endpoint, are returned in the response object.
 
 USAGE:
   scw iot hub get <hub-id ...> [arg=value ...]

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

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List hubs.
+List all Hubs in the specified zone. By default, returned Hubs are ordered by creation date in ascending order, though this can be modified via the `order_by` field.
 
 USAGE:
   scw iot hub list [arg=value ...]
 
 ARGS:
-  [order-by]          Ordering of requested hub (name_asc | name_desc | status_asc | status_desc | product_plan_asc | product_plan_desc | created_at_asc | created_at_desc | updated_at_asc | updated_at_desc)
-  [project-id]        Filter on project
-  [name]              Filter on the name
-  [organization-id]   Filter on the organization
+  [order-by]          Sort order of Hubs in the response (name_asc | name_desc | status_asc | status_desc | product_plan_asc | product_plan_desc | created_at_asc | created_at_desc | updated_at_asc | updated_at_desc)
+  [project-id]        Only list Hubs of this Project ID
+  [name]              Hub name
+  [organization-id]   Only list Hubs of this Organization ID
   [region=fr-par]     Region to target. If none is passed will use default region from the config (fr-par | all)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-iot-hub-set-ca-usage.golden

@@ -1,14 +1,14 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Set the certificate authority of a hub.
+Set a particular PEM-encoded certificate, specified by the Hub ID.
 
 USAGE:
   scw iot hub set-ca <hub-id ...> [arg=value ...]
 
 ARGS:
   hub-id               Hub ID
-  ca-cert-pem          The CA's PEM-encoded certificate
-  challenge-cert-pem   Proof of possession PEM-encoded certificate
+  ca-cert-pem          CA's PEM-encoded certificate
+  challenge-cert-pem   Proof of possession of PEM-encoded certificate
   [region=fr-par]      Region to target. If none is passed will use default region from the config (fr-par)
 
 FLAGS:

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

@@ -1,16 +1,16 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a hub.
+Update the parameters of an existing IoT Hub, specified by its Hub ID.
 
 USAGE:
   scw iot hub update <hub-id ...> [arg=value ...]
 
 ARGS:
-  hub-id                              Hub ID
+  hub-id                              ID of the Hub you want to update
   [name]                              Hub name (up to 255 characters)
-  [product-plan]                      Hub feature set (plan_unknown | plan_shared | plan_dedicated | plan_ha)
+  [product-plan]                      Hub product plan (plan_unknown | plan_shared | plan_dedicated | plan_ha)
   [disable-events]                    Disable Hub events
-  [events-topic-prefix]               Hub events topic prefix
+  [events-topic-prefix]               Topic prefix of Hub events
   [enable-device-auto-provisioning]   Enable device auto provisioning
   [twins-graphite-config.push-uri]    
   [region=fr-par]                     Region to target. If none is passed will use default region from the config (fr-par)

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

@@ -7,9 +7,9 @@ USAGE:
 
 ARGS:
   [order-by]        Ordering of requested routes (name_asc | name_desc | type_asc | type_desc | created_at_asc | created_at_desc)
-  [name]            Filter on Network name
-  [hub-id]          Filter on the hub
-  [topic-prefix]    Filter on the topic prefix
+  [name]            Network name to filter for
+  [hub-id]          Hub ID to filter for
+  [topic-prefix]    Topic prefix to filter for
   [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par | all)
 
 FLAGS:

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

@@ -1,22 +1,22 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Multiple route kinds can be created:
-- Database Route.
+Multiple kinds of routes can be created, such as:
+- Database Route
   Create a route that will record subscribed MQTT messages into your database.
   <b>You need to manage the database by yourself</b>.
 - REST Route.
   Create a route that will call a REST API on received subscribed MQTT messages.
 - S3 Routes.
   Create a route that will put subscribed MQTT messages into an S3 bucket.
-  You need to create the bucket yourself and grant us write access.
-  The grant can be done with s3cmd (`s3cmd setacl s3://<my-bucket> --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031`).
+  You need to create the bucket yourself and grant write access.
+  Granting can be done with s3cmd (`s3cmd setacl s3://<my-bucket> --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031`).
 
 USAGE:
   scw iot route create [arg=value ...]
 
 ARGS:
   [name=<generated>]            Route name
-  [hub-id]                      ID of the route's hub
+  [hub-id]                      Hub ID of the route
   [topic]                       Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters
   [s3-config.bucket-region]     
   [s3-config.bucket-name]       

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

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

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a route.
+Get information for a particular route, specified by the route ID. The response returns full details of the route, including its type, the topic it subscribes to and its configuration.
 
 USAGE:
   scw iot route get <route-id ...> [arg=value ...]

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

@@ -1,14 +1,14 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List routes.
+List all routes in the specified region. By default, returned routes are ordered by creation date in ascending order, though this can be modified via the `order_by` field.
 
 USAGE:
   scw iot route list [arg=value ...]
 
 ARGS:
   [order-by]        Ordering of requested routes (name_asc | name_desc | hub_id_asc | hub_id_desc | type_asc | type_desc | created_at_asc | created_at_desc)
-  [hub-id]          Filter on the hub
-  [name]            Filter on route's name
+  [hub-id]          Hub ID to filter for
+  [name]            Route name to filter for
   [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par | all)
 
 FLAGS:

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

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a route.
+Update the parameters of an existing route, specified by its route ID.
 
 USAGE:
   scw iot route update [arg=value ...]