docs(flexIP): revamp api documentation (#3034)

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

cmd/scw/testdata/test-all-usage-fip-ip-attach-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Attach a Flexible IP to a server.
+Attach an existing flexible IP to a specified Elastic Metal server.
 
 USAGE:
   scw fip ip attach [arg=value ...]
 
 ARGS:
-  fips-ids.{index}   A list of Flexible IP IDs to attach
-  server-id          A server ID on which to attach the Flexible IPs
+  fips-ids.{index}   List of flexible IP IDs to attach to a server
+  server-id          ID of the server on which to attach the flexible IPs
   [zone=fr-par-1]    Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-create-usage.golden

@@ -1,17 +1,17 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a Flexible IP.
+Generate a new flexible IP within a given zone, specifying its configuration including Project ID and description.
 
 USAGE:
   scw fip ip create [arg=value ...]
 
 ARGS:
   [project-id]      Project ID to use. If none is passed the default project ID will be used
-  [description]     Description to associate with the Flexible IP, max 255 characters
-  [tags.{index}]    Tags to associate to the Flexible IP
-  [server-id]       Server ID on which to attach the created Flexible IP
-  [reverse]         Reverse DNS value
-  [is-ipv6]         If true, creates a Flexible IP with an ipv6 address
+  [description]     Flexible IP description (max. of 255 characters)
+  [tags.{index}]    Tags to associate to the flexible IP
+  [server-id]       ID of the server to which the newly created flexible IP will be attached.
+  [reverse]         Value of the reverse DNS
+  [is-ipv6]         Defines whether the flexible IP has an IPv6 address.
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-delete-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a Flexible IP.
+Delete an existing flexible IP, specified by its ID and zone. Note that deleting a flexible IP is permanent and cannot be undone.
 
 USAGE:
   scw fip ip delete <fip-id ...> [arg=value ...]
 
 ARGS:
-  fip-id            ID of the Flexible IP to delete
+  fip-id            ID of the flexible IP to delete
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-detach-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Detach a Flexible IP from a server.
+Detach an existing flexible IP from a specified Elastic Metal server.
 
 USAGE:
   scw fip ip detach [arg=value ...]
 
 ARGS:
-  fips-ids.{index}   A list of Flexible IP IDs to detach
+  fips-ids.{index}   List of flexible IP IDs to detach from a server. Multiple IDs can be provided. Note that flexible IPs must belong to the same MAC group.
   [zone=fr-par-1]    Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-get-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a Flexible IP.
+Retrieve information about an existing flexible IP, specified by its ID and zone. Its full details, including Project ID, description and status, are returned in the response object.
 
 USAGE:
   scw fip ip get <fip-id ...> [arg=value ...]
 
 ARGS:
-  fip-id            Flexible IP ID
+  fip-id            ID of the flexible IP
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-list-usage.golden

@@ -1,17 +1,17 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List Flexible IPs.
+List all flexible IPs within a given zone.
 
 USAGE:
   scw fip ip list [arg=value ...]
 
 ARGS:
-  [order-by]             The sort order of the returned Flexible IPs (created_at_asc | created_at_desc)
-  [tags.{index}]         Filter Flexible IPs with one or more matching tags
-  [status.{index}]       Filter Flexible IPs by status (unknown | ready | updating | attached | error | detaching | locked)
-  [server-ids.{index}]   Filter Flexible IPs by server IDs
-  [project-id]           Filter Flexible IPs by project ID
-  [organization-id]      Filter Flexible IPs by organization ID
+  [order-by]             Sort order of the returned flexible IPs (created_at_asc | created_at_desc)
+  [tags.{index}]         Filter by tag, only flexible IPs with one or more matching tags will be returned
+  [status.{index}]       Filter by status, only flexible IPs with this status will be returned (unknown | ready | updating | attached | error | detaching | locked)
+  [server-ids.{index}]   Filter by server IDs, only flexible IPs with these server IDs will be returned
+  [project-id]           Filter by Project ID, only flexible IPs from this Project will be returned
+  [organization-id]      Filter by Organization ID, only flexible IPs from this Organization will be returned
   [zone=fr-par-1]        Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1 | all)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-update-usage.golden

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a Flexible IP.
+Update the parameters of an existing flexible IP, specified by its ID and zone. These parameters include tags and description.
 
 USAGE:
   scw fip ip update <fip-id ...> [arg=value ...]
 
 ARGS:
-  fip-id            ID of the Flexible IP to update
-  [description]     Description to associate with the Flexible IP, max 255 characters
-  [tags.{index}]    Tags to associate with the Flexible IP
-  [reverse]         Reverse DNS value
+  fip-id            ID of the flexible IP to update
+  [description]     Flexible IP description (max. 255 characters)
+  [tags.{index}]    Tags associated with the flexible IP
+  [reverse]         Value of the reverse DNS
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-ip-usage.golden

@@ -1,19 +1,19 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-A Flexible IP can be attached to any server in the same zone.
-A server can be linked with multiple Flexible IPs attached to it.
+A flexible IP can be attached to any Elastic Metal server within the same zone.
+Multiple flexible IPs can be attached to a server.
 
 USAGE:
   scw fip ip <command>
 
 AVAILABLE COMMANDS:
-  attach      Attach a Flexible IP to a server
-  create      Create a Flexible IP
-  delete      Delete a Flexible IP
-  detach      Detach a Flexible IP from a server
-  get         Get a Flexible IP
-  list        List Flexible IPs
-  update      Update a Flexible IP
+  attach      Attach an existing flexible IP to a server
+  create      Create a new flexible IP
+  delete      Delete an existing flexible IP
+  detach      Detach an existing flexible IP from a server
+  get         Get an existing flexible IP
+  list        List flexible IPs
+  update      Update an existing flexible IP
 
 FLAGS:
   -h, --help   help for ip

cmd/scw/testdata/test-all-usage-fip-mac-create-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Generate a virtual MAC on a given Flexible IP.
+Generate a virtual MAC (Media Access Control) address on an existing flexible IP.
 
 USAGE:
   scw fip mac create [arg=value ...]
 
 ARGS:
-  fip-id            Flexible IP ID on which to generate a Virtual MAC
+  fip-id            ID of the flexible IP for which to generate a virtual MAC
   mac-type          TODO (unknown_type | vmware | xen | kvm)
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 

cmd/scw/testdata/test-all-usage-fip-mac-delete-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Remove a virtual MAC from a Flexible IP.
+Detach a given MAC (Media Access Control) address from an existing flexible IP.
 
 USAGE:
   scw fip mac delete [arg=value ...]
 
 ARGS:
-  fip-id            Flexible IP ID from which to delete the Virtual MAC
+  fip-id            ID of the flexible IP from which to delete the virtual MAC
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-mac-duplicate-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Duplicate a Virtual MAC from a given Flexible IP onto another attached on the same server.
+Duplicate a virtual MAC address from a given flexible IP to another flexible IP attached to the same server.
 
 USAGE:
   scw fip mac duplicate [arg=value ...]
 
 ARGS:
-  fip-id                  Flexible IP ID on which to duplicate the Virtual MAC
-  duplicate-from-fip-id   Flexible IP ID to duplicate the Virtual MAC from
+  fip-id                  ID of the flexible IP on which to duplicate the virtual MAC
+  duplicate-from-fip-id   ID of the flexible IP to duplicate the Virtual MAC from
   [zone=fr-par-1]         Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-fip-mac-move-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Move a Virtual MAC from a given Flexible IP onto another Flexible IP.
+Relocate a virtual MAC (Media Access Control) address from an existing flexible IP to a different flexible IP.
 
 USAGE:
   scw fip mac move [arg=value ...]

cmd/scw/testdata/test-all-usage-fip-mac-usage.golden

@@ -6,10 +6,10 @@ USAGE:
   scw fip mac <command>
 
 AVAILABLE COMMANDS:
-  create      Generate a virtual MAC on a given Flexible IP
-  delete      Remove a virtual MAC from a Flexible IP
-  duplicate   Duplicate a Virtual MAC
-  move        Move a virtual MAC
+  create      Generate a virtual MAC address on an existing flexible IP
+  delete      Detach a given virtual MAC address from an existing flexible IP
+  duplicate   Duplicate a virtual MAC address to another flexible IP
+  move        Relocate an existing virtual MAC address to a different flexible IP
 
 FLAGS:
   -h, --help   help for mac