docs(pgw): revamp public gateways API doc (#2871)

Author: scaleway-bot

cmd/scw/testdata/test-all-usage-vpc-gw-dh-cpusage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-DHCP configuration allows you to set parameters for assignment of IP addresses to devices on a Private Network attached to a VPC Public Gateway (subnet, lease time etc).
+These objects define a DHCP configuration, i.e. how IP addresses should be assigned to devices on a Private Network attached to a Public Gateway. Definable parameters include the subnet for the DHCP server, the validity  period for DHCP entries, whether to use dynamic pooling, and more. A DHCP configuration object has a DHCP ID, which can then be used as part of a  call to create or update a Gateway Network. This lets you attach an existing DHCP configuration to a Public Gateway attached to a Private Network. Similarly, you can use a DHCP ID as a query parameter to list Gateway Networks which use this DHCP configuration object.
 
 USAGE:
   scw vpc-gw dhcp <command>

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-create-usage.golden

@@ -1,28 +1,28 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a DHCP configuration.
+Create a new DHCP configuration object, containing settings for the assignment of IP addresses to devices on a Private Network attached to a Public Gateway. The response object includes the ID of the DHCP configuration object. You can use this ID as part of a call to `Create a Public Gateway connection to a Private Network` or `Update a Public Gateway connection to a Private Network` to directly apply this DHCP configuration.
 
 USAGE:
   scw vpc-gw dhcp create [arg=value ...]
 
 ARGS:
   [project-id]                     Project ID to use. If none is passed the default project ID will be used
   subnet                           Subnet for the DHCP server
-  [address]                        Address of the DHCP server. This will be the gateway's address in the private network. Defaults to the first address of the subnet
-  [pool-low]                       Low IP (included) of the dynamic address pool
-  [pool-high]                      High IP (included) of the dynamic address pool
-  [enable-dynamic]                 Whether to enable dynamic pooling of IPs
+  [address]                        IP address of the DHCP server. This will be the gateway's address in the Private Network. Defaults to the first address of the subnet
+  [pool-low]                       Low IP (inclusive) of the dynamic address pool. Must be in the config's subnet. Defaults to the second address of the subnet
+  [pool-high]                      High IP (inclusive) of the dynamic address pool. Must be in the config's subnet. Defaults to the last address of the subnet
+  [enable-dynamic]                 Defines whether to enable dynamic pooling of IPs. When false, only pre-existing DHCP reservations will be handed out. Defaults to true
   [valid-lifetime.seconds]         
   [valid-lifetime.nanos]           
   [renew-timer.seconds]            
   [renew-timer.nanos]              
   [rebind-timer.seconds]           
   [rebind-timer.nanos]             
-  [push-default-route]             Whether the gateway should push a default route to DHCP clients or only hand out IPs. Defaults to true
-  [push-dns-server]                Whether the gateway should push custom DNS servers to clients
-  [dns-servers-override.{index}]   Override the DNS server list pushed to DHCP clients, instead of the gateway itself
-  [dns-search.{index}]             Additional DNS search paths
-  [dns-local-name]                 TLD given to hosts in the Private Network
+  [push-default-route]             Defines whether the gateway should push a default route to DHCP clients or only hand out IPs. Defaults to true
+  [push-dns-server]                Defines whether the gateway should push custom DNS servers to clients. This allows for Instance hostname -> IP resolution. Defaults to true
+  [dns-servers-override.{index}]   Array of DNS server IP addresses used to override the DNS server list pushed to DHCP clients, instead of the gateway itself
+  [dns-search.{index}]             Array of search paths in addition to the pushed DNS configuration
+  [dns-local-name]                 TLD given to hostnames in the Private Network. Allowed characters are `a-z0-9-.`. Defaults to the slugified Private Network name if created along a GatewayNetwork, or else to `priv`
   [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 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-delete-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a DHCP configuration.
+Delete a DHCP configuration object, identified by its DHCP ID. Note that you cannot delete a DHCP configuration object that is currently being used by a Gateway Network.
 
 USAGE:
   scw vpc-gw dhcp delete <dhcp-id ...> [arg=value ...]
 
 ARGS:
-  dhcp-id           DHCP config id to delete
+  dhcp-id           DHCP configuration ID 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 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-create-usage.golden

@@ -1,14 +1,14 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a static DHCP reservation.
+Create a static DHCP reservation, specifying the Gateway Network for the reservation, the MAC address of the target device and the IP address to assign this device. The response is a DHCP entry object, confirming the ID and configuration details of the static DHCP reservation.
 
 USAGE:
   scw vpc-gw dhcp-entry create [arg=value ...]
 
 ARGS:
   [gateway-network-id]   GatewayNetwork on which to create a DHCP reservation
   [mac-address]          MAC address to give a static entry to
-  [ip-address]           IP address to give to the machine
+  [ip-address]           IP address to give to the device
   [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 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-delete-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a DHCP reservation.
+Delete a static DHCP reservation, identified by its DHCP entry ID. Note that you cannot delete DHCP entries of type `lease`, these are deleted automatically when their time-to-live expires.
 
 USAGE:
   scw vpc-gw dhcp-entry delete <dhcp-entry-id ...> [arg=value ...]
 
 ARGS:
-  dhcp-entry-id     DHCP entry ID to delete
+  dhcp-entry-id     ID of the DHCP entry 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 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-get-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get DHCP entries.
+Get a DHCP entry, specified by its DHCP entry ID.
 
 USAGE:
   scw vpc-gw dhcp-entry get <dhcp-entry-id ...> [arg=value ...]

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-list-usage.golden

@@ -1,17 +1,17 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List DHCP entries.
+List DHCP entries, whether dynamically assigned and/or statically reserved. DHCP entries can be filtered by the Gateway Network they are on, their MAC address, IP address, type or hostname.
 
 USAGE:
   scw vpc-gw dhcp-entry list [arg=value ...]
 
 ARGS:
   [order-by]             Order in which to return results (created_at_asc | created_at_desc | ip_address_asc | ip_address_desc | hostname_asc | hostname_desc)
-  [gateway-network-id]   Filter entries based on the gateway network they are on
-  [mac-address]          Filter entries on their MAC address
-  [ip-address]           Filter entries on their IP address
-  [hostname]             Filter entries on their hostname substring
-  [type]                 Filter entries on their type (unknown | reservation | lease)
+  [gateway-network-id]   Filter for entries on this GatewayNetwork
+  [mac-address]          Filter for entries with this MAC address
+  [ip-address]           Filter for entries with this IP address
+  [hostname]             Filter for entries with this hostname substring
+  [type]                 Filter for entries of this type (unknown | reservation | lease)
   [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 | nl-ams-2 | pl-waw-1 | pl-waw-2 | all)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-set-usage.golden

@@ -1,14 +1,14 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Set the list of DHCP reservations attached to a Gateway Network. Reservations are identified by their MAC address, and will sync the current DHCP entry list to the given list, creating, updating or deleting DHCP entries.
+Set the list of DHCP reservations attached to a Gateway Network. Reservations are identified by their MAC address, and will sync the current DHCP entry list to the given list, creating, updating or deleting DHCP entries accordingly.
 
 USAGE:
   scw vpc-gw dhcp-entry set [arg=value ...]
 
 ARGS:
-  [gateway-network-id]                 Gateway Network on which to set DHCP reservation list
+  [gateway-network-id]                 ID of the Gateway Network on which to set DHCP reservation list
   [dhcp-entries.{index}.mac-address]   MAC address to give a static entry to
-  [dhcp-entries.{index}.ip-address]    IP address to give to the machine
+  [dhcp-entries.{index}.ip-address]    IP address to give to the device
   [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 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-update-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a DHCP entry.
+Update the IP address for a DHCP entry, specified by its DHCP entry ID. You can update an existing DHCP entry of any type (`reservation` (static), `lease` (dynamic) or `unknown`), but in manually updating the IP address the entry will necessarily be of type `reservation` after the update.
 
 USAGE:
   scw vpc-gw dhcp-entry update <dhcp-entry-id ...> [arg=value ...]
 
 ARGS:
-  dhcp-entry-id     DHCP entry ID to update
-  [ip-address]      New IP address to give to the machine
+  dhcp-entry-id     ID of the DHCP entry to update
+  [ip-address]      New IP address to give to the device
   [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 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-vpc-gw-dhcp-entry-usage.golden

@@ -1,14 +1,14 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-DHCP entries hold both dynamic DHCP leases (IP addresses dynamically assigned by the gateway to instances) and static user-created DHCP reservations.
+DHCP entries belong to a specified Gateway Network (Public Gateway / Private Network connection). A DHCP entry can hold either a dynamic DHCP lease (an IP address dynamically assigned by the Public Gateway to a device) or a static, user-created DHCP reservation.
 
 USAGE:
   scw vpc-gw dhcp-entry <command>
 
 AVAILABLE COMMANDS:
-  create      Create a static DHCP reservation
-  delete      Delete a DHCP reservation
-  get         Get DHCP entries
+  create      Create a DHCP entry
+  delete      Delete a DHCP entry
+  get         Get a DHCP entry
   list        List DHCP entries
   set         Set all DHCP reservations on a Gateway Network
   update      Update a DHCP entry