docs(domains&dns): api documentation revamp (#3033)

scaleway-bot · remyleone · web-flow · commit af2d41c3dcfc · 2023-04-17T14:19:42.000Z
Co-authored-by: Rémy Léone &lt;rleone@scaleway.com&gt;
diff --git a/cmd/scw/testdata/test-all-usage-dns-certificate-create-usage.golden b/cmd/scw/testdata/test-all-usage-dns-certificate-create-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create or return the zone TLS certificate.
+Create a new TLS certificate or retrieve information about an existing TLS certificate.
 
 USAGE:
   scw dns certificate create <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-certificate-delete-usage.golden b/cmd/scw/testdata/test-all-usage-dns-certificate-delete-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete an TLS certificate.
+Delete an existing TLS certificate specified by its DNS zone. Deleting a TLS certificate is permanent and cannot be undone.
 
 USAGE:
   scw dns certificate delete <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-certificate-get-usage.golden b/cmd/scw/testdata/test-all-usage-dns-certificate-get-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the zone TLS certificate if it exists.
+Get the DNS zone's TLS certificate. If you do not have a certificate, the ouptut returns `no certificate found`.
 
 USAGE:
   scw dns certificate get <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-certificate-list-usage.golden b/cmd/scw/testdata/test-all-usage-dns-certificate-list-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List all user TLS certificates.
+List all the TLS certificates a user has created, specified by the user's Project ID and the DNS zone.
 
 USAGE:
   scw dns certificate list <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-certificate-usage.golden b/cmd/scw/testdata/test-all-usage-dns-certificate-usage.golden
@@ -6,10 +6,10 @@ USAGE:
   scw dns certificate <command>
 
 AVAILABLE COMMANDS:
-  create      Create or return the zone TLS certificate
-  delete      Delete an TLS certificate
-  get         Get the zone TLS certificate if it exists
-  list        List all user TLS certificates
+  create      Create or get the DNS zone's TLS certificate
+  delete      Delete a TLS certificate
+  get         Get a DNS zone's TLS certificate
+  list        List a user's TLS certificates
 
 FLAGS:
   -h, --help   help for certificate
diff --git a/cmd/scw/testdata/test-all-usage-dns-record-bulk-update-usage.golden b/cmd/scw/testdata/test-all-usage-dns-record-bulk-update-usage.golden
@@ -1,28 +1,20 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Only available with default NS.<br/>
-Send a list of actions and records.
+Update records within a DNS zone that has default name servers and perform several actions on your records.
 
-Action can be:
- - add:
-  - Add new record
-  - Can be more specific and add a new IP to an existing A record for example
- - set:
-  - Edit a record
-  - Can be more specific and edit an IP from an existing A record for example
- - delete:
-  - Delete a record
-  - Can be more specific and delete an IP from an existing A record for example
- - clear:
-  - Delete all records from a DNS zone
+Actions include:
+ - add: allows you to add a new record or add a new IP to an existing A record, for example
+ - set: allows you to edit a record or edit an IP from an existing A record, for example
+ - delete: allows you to delete a record or delete an IP from an existing A record, for example
+ - clear: allows you to delete all records from a DNS zone
 
 All edits will be versioned.
 
 USAGE:
   scw dns record bulk-update <dns-zone ...> [arg=value ...]
 
 ARGS:
-  dns-zone                                                                                 The DNS zone where the DNS zone records will be updated
+  dns-zone                                                                                 DNS zone in which to update the DNS zone records
   [changes.{index}.add.records.{index}.data]                                               
   [changes.{index}.add.records.{index}.name]                                               
   [changes.{index}.add.records.{index}.priority]                                           
@@ -73,9 +65,9 @@ ARGS:
   [changes.{index}.delete.id-fields.type]                                                   (unknown | A | AAAA | CNAME | TXT | SRV | TLSA | MX | NS | PTR | CAA | ALIAS | LOC | SSHFP | HINFO | RP | URI | DS | NAPTR | DNAME)
   [changes.{index}.delete.id-fields.data]                                                  
   [changes.{index}.delete.id-fields.ttl]                                                   
-  [return-all-records]                                                                     Whether or not to return all the records
-  [disallow-new-zone-creation]                                                             Forbid the creation of the target zone if not existing (default action is yes)
-  [serial]                                                                                 Don't use the autoincremenent serial but the provided one (0 to keep the same)
+  [return-all-records]                                                                     Specifies whether or not to return all the records
+  [disallow-new-zone-creation]                                                             Disable the creation of the target zone if it does not exist. Target zone creation is disabled by default
+  [serial]                                                                                 Use the provided serial (0) instead of the auto-increment serial
 
 FLAGS:
   -h, --help   help for bulk-update
diff --git a/cmd/scw/testdata/test-all-usage-dns-record-clear-usage.golden b/cmd/scw/testdata/test-all-usage-dns-record-clear-usage.golden
@@ -1,14 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Only available with default NS.<br/>
-Delete all the records from a DNS zone.
+Delete all records within a DNS zone that has default name servers.<br/>
 All edits will be versioned.
 
 USAGE:
   scw dns record clear <dns-zone ...> [arg=value ...]
 
 ARGS:
-  dns-zone   The DNS zone to clear
+  dns-zone   DNS zone to clear
 
 FLAGS:
   -h, --help   help for clear
diff --git a/cmd/scw/testdata/test-all-usage-dns-record-list-nameservers-usage.golden b/cmd/scw/testdata/test-all-usage-dns-record-list-nameservers-usage.golden
@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Returns a list of Nameservers and their optional glue records for a DNS zone.
+Retrieve a list of name servers within a DNS zone and their optional glue records.
 
 USAGE:
   scw dns record list-nameservers <dns-zone ...> [arg=value ...]
 
 ARGS:
-  [project-id]   The project ID on which to filter the returned DNS zone nameservers
-  dns-zone       The DNS zone on which to filter the returned DNS zone nameservers
+  [project-id]   Project ID on which to filter the returned DNS zone name servers
+  dns-zone       DNS zone on which to filter the returned DNS zone name servers
 
 FLAGS:
   -h, --help   help for list-nameservers
diff --git a/cmd/scw/testdata/test-all-usage-dns-record-list-usage.golden b/cmd/scw/testdata/test-all-usage-dns-record-list-usage.golden
@@ -1,18 +1,18 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Returns a list of DNS records of a DNS zone with default NS.
-You can filter the records by type and name.
+Retrieve a list of DNS records within a DNS zone that has default name servers.
+You can filter records by type and name.
 
 USAGE:
   scw dns record list <dns-zone ...> [arg=value ...]
 
 ARGS:
-  [project-id]   The project ID on which to filter the returned DNS zone records
-  [order-by]     The sort order of the returned DNS zone records (name_asc | name_desc)
-  dns-zone       The DNS zone on which to filter the returned DNS zone records
-  [name]         The name on which to filter the returned DNS zone records
-  [type]         The record type on which to filter the returned DNS zone records (unknown | A | AAAA | CNAME | TXT | SRV | TLSA | MX | NS | PTR | CAA | ALIAS | LOC | SSHFP | HINFO | RP | URI | DS | NAPTR | DNAME)
-  [id]           The record ID on which to filter the returned DNS zone records
+  [project-id]   Project ID on which to filter the returned DNS zone records
+  [order-by]     Sort order of the returned DNS zone records (name_asc | name_desc)
+  dns-zone       DNS zone on which to filter the returned DNS zone records
+  [name]         Name on which to filter the returned DNS zone records
+  [type]         Record type on which to filter the returned DNS zone records (unknown | A | AAAA | CNAME | TXT | SRV | TLSA | MX | NS | PTR | CAA | ALIAS | LOC | SSHFP | HINFO | RP | URI | DS | NAPTR | DNAME)
+  [id]           Record ID on which to filter the returned DNS zone records
 
 FLAGS:
   -h, --help   help for list
diff --git a/cmd/scw/testdata/test-all-usage-dns-record-update-nameservers-usage.golden b/cmd/scw/testdata/test-all-usage-dns-record-update-nameservers-usage.golden
@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update DNS zone nameservers and set optional glue records.
+Update name servers within a DNS zone and set optional glue records.
 
 USAGE:
   scw dns record update-nameservers <dns-zone ...> [arg=value ...]
 
 ARGS:
-  dns-zone                  The DNS zone where the DNS zone nameservers will be updated
+  dns-zone                  DNS zone in which to update the DNS zone name servers
   [ns.{index}.name]         
   [ns.{index}.ip.{index}]   
 
diff --git a/cmd/scw/testdata/test-all-usage-dns-record-usage.golden b/cmd/scw/testdata/test-all-usage-dns-record-usage.golden
@@ -7,13 +7,13 @@ USAGE:
 
 AVAILABLE COMMANDS:
   add                Add a new DNS record
-  bulk-update        Update DNS zone records
-  clear              Clear DNS zone records
+  bulk-update        Update records within a DNS zone
+  clear              Clear records within a DNS zone
   delete             Delete a DNS record
-  list               List DNS zone records
-  list-nameservers   List DNS zone nameservers
+  list               List records within a DNS zone
+  list-nameservers   List name servers within a DNS zone
   set                Update a DNS record
-  update-nameservers Update DNS zone nameservers
+  update-nameservers Update name servers within a DNS zone
 
 FLAGS:
   -h, --help   help for record
diff --git a/cmd/scw/testdata/test-all-usage-dns-tsig-key-delete-usage.golden b/cmd/scw/testdata/test-all-usage-dns-tsig-key-delete-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete the DNS zone TSIG Key.
+Delete an existing TSIG key specified by its DNS zone. Deleting a TSIG key is permanent and cannot be undone.
 
 USAGE:
   scw dns tsig-key delete <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-tsig-key-get-usage.golden b/cmd/scw/testdata/test-all-usage-dns-tsig-key-get-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the DNS zone TSIG Key to allow AXFR request.
+Retrieve information about the TSIG key of a given DNS zone to allow AXFR requests.
 
 USAGE:
   scw dns tsig-key get <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-tsig-key-usage.golden b/cmd/scw/testdata/test-all-usage-dns-tsig-key-usage.golden
@@ -6,8 +6,8 @@ USAGE:
   scw dns tsig-key <command>
 
 AVAILABLE COMMANDS:
-  delete      Delete the DNS zone TSIG Key
-  get         Get the DNS zone TSIG Key
+  delete      Delete the DNS zone's TSIG key
+  get         Get the DNS zone's TSIG key
 
 FLAGS:
   -h, --help   help for tsig-key
diff --git a/cmd/scw/testdata/test-all-usage-dns-usage.golden b/cmd/scw/testdata/test-all-usage-dns-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Manage your DNS zones and records.
+Manage your domains, DNS zones and records with the Domains and DNS API.
 
 USAGE:
   scw dns <command>
diff --git a/cmd/scw/testdata/test-all-usage-dns-version-diff-usage.golden b/cmd/scw/testdata/test-all-usage-dns-version-diff-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get all differences from a previous DNS zone version.
+Access a previous DNS zone version to see the differences from another specific version.
 
 USAGE:
   scw dns version diff <dns-zone-version-id ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-version-list-usage.golden b/cmd/scw/testdata/test-all-usage-dns-version-list-usage.golden
@@ -1,8 +1,7 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a list of DNS zone versions.<br/>
-The maximum version count is 100.<br/>
-If the count reaches this limit, the oldest version will be deleted after each new modification.
+Retrieve a list of a DNS zone's versions.<br/>
+The maximum version count is 100. If the count reaches this limit, the oldest version will be deleted after each new modification.
 
 USAGE:
   scw dns version list <dns-zone ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-version-restore-usage.golden b/cmd/scw/testdata/test-all-usage-dns-version-restore-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Restore and activate a previous DNS zone version.
+Restore and activate a version of a specific DNS zone.
 
 USAGE:
   scw dns version restore <dns-zone-version-id ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-version-show-usage.golden b/cmd/scw/testdata/test-all-usage-dns-version-show-usage.golden
@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a list of records from a previous DNS zone version.
+Retrieve a list of records from a specific DNS zone version.
 
 USAGE:
   scw dns version show <dns-zone-version-id ...> [arg=value ...]
diff --git a/cmd/scw/testdata/test-all-usage-dns-version-usage.golden b/cmd/scw/testdata/test-all-usage-dns-version-usage.golden
@@ -6,10 +6,10 @@ USAGE:
   scw dns version <command>
 
 AVAILABLE COMMANDS:
-  diff        Get DNS zone version diff
-  list        List DNS zone versions
-  restore     Restore DNS zone version
-  show        List DNS zone version records
+  diff        Access differences from a specific DNS zone version
+  list        List versions of a DNS zone
+  restore     Restore a DNS zone version
+  show        List records from a given version of a specific DNS zone
 
 FLAGS:
   -h, --help   help for version
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-clone-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-clone-usage.golden
@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Clone an existed DNS zone with all its records into a new one.
+Clone an existing DNS zone with all its records into a new DNS zone.
 
 USAGE:
   scw dns zone clone [arg=value ...]
 
 ARGS:
-  dns-zone        The DNS zone to clone
-  dest-dns-zone   The destinaton DNS zone
-  [overwrite]     Whether or not the destination DNS zone will be overwritten
-  [project-id]    The project ID of the destination DNS zone
+  dns-zone        DNS zone to clone
+  dest-dns-zone   Destination DNS zone in which to clone the chosen DNS zone
+  [overwrite]     Specifies whether or not the destination DNS zone will be overwritten
+  [project-id]    Project ID of the destination DNS zone
 
 FLAGS:
   -h, --help   help for clone
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-create-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-create-usage.golden
@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a new DNS zone.
+Create a new DNS zone specified by the domain name, the subdomain and the Project ID.
 
 USAGE:
   scw dns zone create [arg=value ...]
 
 ARGS:
-  domain         The domain of the DNS zone to create
-  subdomain      The subdomain of the DNS zone to create
+  domain         Domain in which to crreate the DNS zone
+  subdomain      Subdomain of the DNS zone to create
   [project-id]   Project ID to use. If none is passed the default project ID will be used
 
 FLAGS:
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-delete-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-delete-usage.golden
@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a DNS zone and all it's records.
+Delete a DNS zone and all its records.
 
 USAGE:
   scw dns zone delete <dns-zone ...> [arg=value ...]
 
 ARGS:
-  dns-zone       The DNS zone to delete
+  dns-zone       DNS zone to delete
   [project-id]   Project ID to use. If none is passed the default project ID will be used
 
 FLAGS:
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-export-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-export-usage.golden
@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get a DNS zone in a given format with default NS.
+Export a DNS zone with default name servers, in a specific format.
 
 USAGE:
   scw dns zone export <dns-zone ...> [arg=value ...]
 
 ARGS:
-  dns-zone        The DNS zone to export
-  [format=bind]   Format for DNS zone (unknown_raw_format | bind)
+  dns-zone        DNS zone to export
+  [format=bind]   DNS zone format (unknown_raw_format | bind)
 
 FLAGS:
   -h, --help   help for export
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-import-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-import-usage.golden
@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Import and replace records from a given provider format with default NS.
+Import and replace the format of records from a given provider, with default name servers.
 
 USAGE:
   scw dns zone import <dns-zone ...> [arg=value ...]
 
 ARGS:
-  dns-zone                           The DNS zone to import
+  dns-zone                           DNS zone to import
   [project-id]                       Project ID to use. If none is passed the default project ID will be used
   [bind-source.content]               (Support file loading with @/path/to/file)
   [axfr-source.name-server]          
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-list-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-list-usage.golden
@@ -1,17 +1,16 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Returns a list of manageable DNS zones.
-You can filter the DNS zones by domain name.
+Retrieve the list of DNS zones you can manage and filter DNS zones associated with specific domain names.
 
 USAGE:
   scw dns zone list [arg=value ...]
 
 ARGS:
-  [project-id]        The project ID on which to filter the returned DNS zones
-  [order-by]          The sort order of the returned DNS zones (domain_asc | domain_desc | subdomain_asc | subdomain_desc)
-  [domain]            The domain on which to filter the returned DNS zones
-  [dns-zone]          The DNS zone on which to filter the returned DNS zones
-  [organization-id]   The organization ID on which to filter the returned DNS zones
+  [project-id]        Project ID on which to filter the returned DNS zones
+  [order-by]          Sort order of the returned DNS zones (domain_asc | domain_desc | subdomain_asc | subdomain_desc)
+  [domain]            Domain on which to filter the returned DNS zones
+  [dns-zone]          DNS zone on which to filter the returned DNS zones
+  [organization-id]   Organization ID on which to filter the returned DNS zones
 
 FLAGS:
   -h, --help   help for list
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-refresh-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-refresh-usage.golden
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-update-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-update-usage.golden
diff --git a/cmd/scw/testdata/test-all-usage-dns-zone-usage.golden b/cmd/scw/testdata/test-all-usage-dns-zone-usage.golden
diff --git a/cmd/scw/testdata/test-main-usage-usage.golden b/cmd/scw/testdata/test-main-usage-usage.golden
diff --git a/docs/commands/dns.md b/docs/commands/dns.md
diff --git a/internal/namespaces/domain/v2beta1/domain_cli.go b/internal/namespaces/domain/v2beta1/domain_cli.go
