docs(flexible_ip): revamp (#616)

scaleway-bot · web-flow · commit cf387cadf2d7 · 2023-04-17T14:48:30.000Z
diff --git a/packages/clients/src/api/flexibleip/v1alpha1/api.gen.ts b/packages/clients/src/api/flexibleip/v1alpha1/api.gen.ts
@@ -54,7 +54,8 @@ export class API extends ParentAPI {
   ]
 
   /**
-   * Create a Flexible IP.
+   * Create a new flexible IP. Generate a new flexible IP within a given zone,
+   * specifying its configuration including Project ID and description.
    *
    * @param request - The request {@link CreateFlexibleIPRequest}
    * @returns A Promise of FlexibleIP
@@ -76,7 +77,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Get a Flexible IP.
+   * Get an existing 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.
    *
    * @param request - The request {@link GetFlexibleIPRequest}
    * @returns A Promise of FlexibleIP
@@ -143,7 +146,7 @@ export class API extends ParentAPI {
     )
 
   /**
-   * List Flexible IPs.
+   * List flexible IPs. List all flexible IPs within a given zone.
    *
    * @param request - The request {@link ListFlexibleIPsRequest}
    * @returns A Promise of ListFlexibleIPsResponse
@@ -152,7 +155,9 @@ export class API extends ParentAPI {
     enrichForPagination('flexibleIps', this.pageOfListFlexibleIPs, request)
 
   /**
-   * Update a Flexible IP.
+   * Update an existing flexible IP. Update the parameters of an existing
+   * flexible IP, specified by its ID and zone. These parameters include tags
+   * and description.
    *
    * @param request - The request {@link UpdateFlexibleIPRequest}
    * @returns A Promise of FlexibleIP
@@ -174,7 +179,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Delete a Flexible IP.
+   * Delete an existing 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.
    *
    * @param request - The request {@link DeleteFlexibleIPRequest}
    */
@@ -188,7 +195,8 @@ export class API extends ParentAPI {
     })
 
   /**
-   * Attach a Flexible IP to a server.
+   * Attach an existing flexible IP to a server. Attach an existing flexible IP
+   * to a specified Elastic Metal server.
    *
    * @param request - The request {@link AttachFlexibleIPRequest}
    * @returns A Promise of AttachFlexibleIPsResponse
@@ -210,7 +218,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Detach a Flexible IP from a server.
+   * Detach an existing flexible IP from a server. Detach an existing flexible
+   * IP from a specified Elastic Metal server.
    *
    * @param request - The request {@link DetachFlexibleIPRequest}
    * @returns A Promise of DetachFlexibleIPsResponse
@@ -232,7 +241,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Generate a virtual MAC on a given Flexible IP.
+   * Generate a virtual MAC address on an existing flexible IP. Generate a
+   * virtual MAC (Media Access Control) address on an existing flexible IP.
    *
    * @param request - The request {@link GenerateMACAddrRequest}
    * @returns A Promise of FlexibleIP
@@ -254,8 +264,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Duplicate a Virtual MAC. Duplicate a Virtual MAC from a given Flexible IP
-   * onto another attached on the same server.
+   * Duplicate a virtual MAC address to another flexible IP. Duplicate a virtual
+   * MAC address from a given flexible IP to another flexible IP attached to the
+   * same server.
    *
    * @param request - The request {@link DuplicateMACAddrRequest}
    * @returns A Promise of FlexibleIP
@@ -277,8 +288,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Move a virtual MAC. Move a Virtual MAC from a given Flexible IP onto
-   * another Flexible IP.
+   * Relocate an existing virtual MAC address to a different flexible IP.
+   * Relocate a virtual MAC (Media Access Control) address from an existing
+   * flexible IP to a different flexible IP.
    *
    * @param request - The request {@link MoveMACAddrRequest}
    * @returns A Promise of FlexibleIP
@@ -300,7 +312,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Remove a virtual MAC from a Flexible IP.
+   * Detach a given virtual MAC address from an existing flexible IP. Detach a
+   * given MAC (Media Access Control) address from an existing flexible IP.
    *
    * @param request - The request {@link DeleteMACAddrRequest}
    */
diff --git a/packages/clients/src/api/flexibleip/v1alpha1/types.gen.ts b/packages/clients/src/api/flexibleip/v1alpha1/types.gen.ts
@@ -25,84 +25,84 @@ export type MACAddressType = 'unknown_type' | 'vmware' | 'xen' | 'kvm'
 
 /** Attach flexible i ps response. */
 export interface AttachFlexibleIPsResponse {
-  /** Total count of Flexible IPs being updated. */
+  /** Total count of flexible IPs that are being updated. */
   totalCount: number
-  /** Listing of Flexible IPs in updating state. */
+  /** List of flexible IPs in an updating state. */
   flexibleIps: FlexibleIP[]
 }
 
 /** Detach flexible i ps response. */
 export interface DetachFlexibleIPsResponse {
-  /** Total count of Flexible IPs being detached. */
+  /** Total count of flexible IPs that are being detached. */
   totalCount: number
-  /** Listing of Flexible IPs in detaching state. */
+  /** List of flexible IPs in a detaching state. */
   flexibleIps: FlexibleIP[]
 }
 
 /** Flexible ip. */
 export interface FlexibleIP {
-  /** ID of the Flexible IP. */
+  /** ID of the flexible IP. */
   id: string
-  /** Organization ID the Flexible IP is attached to. */
+  /** ID of the Organization the flexible IP is attached to. */
   organizationId: string
-  /** Project ID the Flexible IP is attached to. */
+  /** ID of the Project the flexible IP is attached to. */
   projectId: string
-  /** Description of the Flexible IP. */
+  /** Flexible IP description. */
   description: string
-  /** Tags associated with the Flexible IP. */
+  /** Flexible IP tags. */
   tags: string[]
-  /** Date of last update of the Flexible IP. */
+  /** Date on which the flexible IP was last updated. */
   updatedAt?: Date
-  /** Date of creation of the Flexible IP. */
+  /** Date on which the flexible IP was created. */
   createdAt?: Date
   /**
-   * Status of the Flexible IP.
+   * Flexible IP status.
    *
-   * - Ready : Flexible IP is created and ready to be attached to a server or to
-   *   have a virtual MAC generated.
-   * - Updating: Flexible IP is being attached to a server or a virtual MAC
+   * - Ready : flexible IP is created and ready to be attached to a server or to
+   *   be associated with a virtual MAC.
+   * - Updating: flexible IP is being attached to a server or a virtual MAC
    *   operation is ongoing
-   * - Attached: Flexible IP is attached to a server
-   * - Error: a Flexible IP operation resulted in an error
-   * - Detaching: Flexible IP is being detached from a server
-   * - Locked: Flexible IP resource is locked.
+   * - Attached: flexible IP is attached to a server
+   * - Error: a flexible IP operation resulted in an error
+   * - Detaching: flexible IP is being detached from a server
+   * - Locked: the resource of the flexible IP is locked.
    */
   status: FlexibleIPStatus
-  /** IP of the Flexible IP. */
+  /** IP of the flexible IP. */
   ipAddress: string
-  /** MAC address of the Flexible IP. */
+  /** MAC address of the flexible IP. */
   macAddress?: MACAddress
-  /** ID of the server linked to the Flexible IP. */
+  /** ID of the server linked to the flexible IP. */
   serverId?: string
   /** Reverse DNS value. */
   reverse: string
-  /** Flexible IP Availability Zone. */
+  /** Availability Zone of the flexible IP. */
   zone: Zone
 }
 
 /** List flexible i ps response. */
 export interface ListFlexibleIPsResponse {
-  /** Total count of matching Flexible IPs. */
+  /** Total count of matching flexible IPs. */
   totalCount: number
-  /** Listing of Flexible IPs. */
+  /** List of all flexible IPs. */
   flexibleIps: FlexibleIP[]
 }
 
 /** Mac address. */
 export interface MACAddress {
-  /** ID of the Flexible IP. */
+  /** ID of the flexible IP. */
   id: string
   /** MAC address of the Virtual MAC. */
   macAddress: string
-  /** Virtual MAC type. */
+  /** Type of virtual MAC. */
   macType: MACAddressType
-  /** Virtual MAC status. */
+  /** Status of virtual MAC. */
   status: MACAddressStatus
-  /** Date of last update of the Virtual MAC. */
+  /** Date on which the virtual MAC was last updated. */
   updatedAt?: Date
-  /** Date of creation of the Virtual MAC. */
+  /** Date on which the virtual MAC was created. */
   createdAt?: Date
-  /** MAC Addr IP Availability Zone. */
+  /** MAC address IP Availability Zone. */
   zone: Zone
 }
 
@@ -111,94 +111,102 @@ export type CreateFlexibleIPRequest = {
   zone?: Zone
   /** ID of the project to associate with the Flexible IP. */
   projectId?: string
-  /** Description to associate with the Flexible IP, max 255 characters. */
+  /** Flexible IP description (max. of 255 characters). */
   description: string
-  /** Tags to associate to the Flexible IP. */
+  /** Tags to associate to the flexible IP. */
   tags?: string[]
-  /** Server ID on which to attach the created Flexible IP. */
+  /** ID of the server to which the newly created flexible IP will be attached. */
   serverId?: string
-  /** Reverse DNS value. */
+  /** Value of the reverse DNS. */
   reverse?: string
-  /** If true, creates a Flexible IP with an ipv6 address. */
+  /** Defines whether the flexible IP has an IPv6 address. */
   isIpv6: boolean
 }
 
 export type GetFlexibleIPRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
-  /** Flexible IP ID. */
+  /** ID of the flexible IP. */
   fipId: string
 }
 
 export type ListFlexibleIPsRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
-  /** The sort order of the returned Flexible IPs. */
+  /** Sort order of the returned flexible IPs. */
   orderBy?: ListFlexibleIPsRequestOrderBy
-  /** The page number for the returned Flexible IPs. */
+  /** Page number. */
   page?: number
-  /** The maximum number of Flexible IPs per page. */
+  /** Maximum number of flexible IPs per page. */
   pageSize?: number
-  /** Filter Flexible IPs with one or more matching tags. */
+  /**
+   * Filter by tag, only flexible IPs with one or more matching tags will be
+   * returned.
+   */
   tags?: string[]
-  /** Filter Flexible IPs by status. */
+  /** Filter by status, only flexible IPs with this status will be returned. */
   status?: FlexibleIPStatus[]
-  /** Filter Flexible IPs by server IDs. */
+  /**
+   * Filter by server IDs, only flexible IPs with these server IDs will be
+   * returned.
+   */
   serverIds?: string[]
-  /** Filter Flexible IPs by organization ID. */
+  /**
+   * Filter by Organization ID, only flexible IPs from this Organization will be
+   * returned.
+   */
   organizationId?: string
-  /** Filter Flexible IPs by project ID. */
+  /** Filter by Project ID, only flexible IPs from this Project will be returned. */
   projectId?: string
 }
 
 export type UpdateFlexibleIPRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
-  /** ID of the Flexible IP to update. */
+  /** ID of the flexible IP to update. */
   fipId: string
-  /** Description to associate with the Flexible IP, max 255 characters. */
+  /** Flexible IP description (max. 255 characters). */
   description?: string
-  /** Tags to associate with the Flexible IP. */
+  /** Tags associated with the flexible IP. */
   tags?: string[]
-  /** Reverse DNS value. */
+  /** Value of the reverse DNS. */
   reverse?: string
 }
 
 export type DeleteFlexibleIPRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
-  /** ID of the Flexible IP to delete. */
+  /** ID of the flexible IP to delete. */
   fipId: string
 }
 
 export type AttachFlexibleIPRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
   /**
-   * A list of Flexible IP IDs to attach. Multiple IDs can be provided as long
-   * as Flexible IPs belong to the same MAC groups (see details about MAC
-   * groups).
+   * List of flexible IP IDs to attach to a server. Multiple IDs can be
+   * provided, but note that flexible IPs must belong to the same MAC group (see
+   * details about MAC groups).
    */
   fipsIds: string[]
-  /** A server ID on which to attach the Flexible IPs. */
+  /** ID of the server on which to attach the flexible IPs. */
   serverId: string
 }
 
 export type DetachFlexibleIPRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
   /**
-   * A list of Flexible IP IDs to detach. Multiple IDs can be provided as long
-   * as Flexible IPs belong to the same MAC groups (see details about MAC
-   * groups).
+   * 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.
    */
   fipsIds: string[]
 }
 
 export type GenerateMACAddrRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
-  /** Flexible IP ID on which to generate a Virtual MAC. */
+  /** ID of the flexible IP for which to generate a virtual MAC. */
   fipId: string
   /** TODO. */
   macType: MACAddressType
@@ -208,13 +216,13 @@ export type DuplicateMACAddrRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
   /**
-   * Flexible IP ID on which to duplicate the Virtual MAC. Flexible IPs need to
-   * be attached to the same server.
+   * ID of the flexible IP on which to duplicate the virtual MAC. Note that the
+   * flexible IPs need to be attached to the same server.
    */
   fipId: string
   /**
-   * Flexible IP ID to duplicate the Virtual MAC from. Flexible IPs need to be
-   * attached to the same server.
+   * ID of the flexible IP to duplicate the Virtual MAC from. Note that flexible
+   * IPs need to be attached to the same server.
    */
   duplicateFromFipId: string
 }
@@ -230,9 +238,9 @@ export type DeleteMACAddrRequest = {
   /** Zone to target. If none is passed will use default zone from the config. */
   zone?: Zone
   /**
-   * Flexible IP ID from which to delete the Virtual MAC. If the Flexible IP
-   * belongs to a MAC group, the MAC will be removed from the MAC group and from
-   * the Flexible IP.
+   * ID of the flexible IP from which to delete the virtual MAC. If the flexible
+   * IP belongs to a MAC group, the MAC will be removed from both the MAC group
+   * and flexible IP.
    */
   fipId: string
 }

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,8 @@ export class API extends ParentAPI {`
`54`	`54`	`]`
`55`	`55`
`56`	`56`	`/**`
`57`		`- * Create a Flexible IP.`
	`57`	`+ * Create a new flexible IP. Generate a new flexible IP within a given zone,`
	`58`	`+ * specifying its configuration including Project ID and description.`
`58`	`59`	`*`
`59`	`60`	`* @param request - The request {@link CreateFlexibleIPRequest}`
`60`	`61`	`* @returns A Promise of FlexibleIP`
`@@ -76,7 +77,9 @@ export class API extends ParentAPI {`
`76`	`77`	`)`
`77`	`78`
`78`	`79`	`/**`
`79`		`- * Get a Flexible IP.`
	`80`	`+ * Get an existing flexible IP. Retrieve information about an existing`
	`81`	`+ * flexible IP, specified by its ID and zone. Its full details, including`
	`82`	`+ * Project ID, description and status, are returned in the response object.`
`80`	`83`	`*`
`81`	`84`	`* @param request - The request {@link GetFlexibleIPRequest}`
`82`	`85`	`* @returns A Promise of FlexibleIP`
`@@ -143,7 +146,7 @@ export class API extends ParentAPI {`
`143`	`146`	`)`
`144`	`147`
`145`	`148`	`/**`
`146`		`- * List Flexible IPs.`
	`149`	`+ * List flexible IPs. List all flexible IPs within a given zone.`
`147`	`150`	`*`
`148`	`151`	`* @param request - The request {@link ListFlexibleIPsRequest}`
`149`	`152`	`* @returns A Promise of ListFlexibleIPsResponse`
`@@ -152,7 +155,9 @@ export class API extends ParentAPI {`
`152`	`155`	`enrichForPagination('flexibleIps', this.pageOfListFlexibleIPs, request)`
`153`	`156`
`154`	`157`	`/**`
`155`		`- * Update a Flexible IP.`
	`158`	`+ * Update an existing flexible IP. Update the parameters of an existing`
	`159`	`+ * flexible IP, specified by its ID and zone. These parameters include tags`
	`160`	`+ * and description.`
`156`	`161`	`*`
`157`	`162`	`* @param request - The request {@link UpdateFlexibleIPRequest}`
`158`	`163`	`* @returns A Promise of FlexibleIP`
`@@ -174,7 +179,9 @@ export class API extends ParentAPI {`
`174`	`179`	`)`
`175`	`180`
`176`	`181`	`/**`
`177`		`- * Delete a Flexible IP.`
	`182`	`+ * Delete an existing flexible IP. Delete an existing flexible IP, specified`
	`183`	`+ * by its ID and zone. Note that deleting a flexible IP is permanent and`
	`184`	`+ * cannot be undone.`
`178`	`185`	`*`
`179`	`186`	`* @param request - The request {@link DeleteFlexibleIPRequest}`
`180`	`187`	`*/`
`@@ -188,7 +195,8 @@ export class API extends ParentAPI {`
`188`	`195`	`})`
`189`	`196`
`190`	`197`	`/**`
`191`		`- * Attach a Flexible IP to a server.`
	`198`	`+ * Attach an existing flexible IP to a server. Attach an existing flexible IP`
	`199`	`+ * to a specified Elastic Metal server.`
`192`	`200`	`*`
`193`	`201`	`* @param request - The request {@link AttachFlexibleIPRequest}`
`194`	`202`	`* @returns A Promise of AttachFlexibleIPsResponse`
`@@ -210,7 +218,8 @@ export class API extends ParentAPI {`
`210`	`218`	`)`
`211`	`219`
`212`	`220`	`/**`
`213`		`- * Detach a Flexible IP from a server.`
	`221`	`+ * Detach an existing flexible IP from a server. Detach an existing flexible`
	`222`	`+ * IP from a specified Elastic Metal server.`
`214`	`223`	`*`
`215`	`224`	`* @param request - The request {@link DetachFlexibleIPRequest}`
`216`	`225`	`* @returns A Promise of DetachFlexibleIPsResponse`
`@@ -232,7 +241,8 @@ export class API extends ParentAPI {`
`232`	`241`	`)`
`233`	`242`
`234`	`243`	`/**`
`235`		`- * Generate a virtual MAC on a given Flexible IP.`
	`244`	`+ * Generate a virtual MAC address on an existing flexible IP. Generate a`
	`245`	`+ * virtual MAC (Media Access Control) address on an existing flexible IP.`
`236`	`246`	`*`
`237`	`247`	`* @param request - The request {@link GenerateMACAddrRequest}`
`238`	`248`	`* @returns A Promise of FlexibleIP`
`@@ -254,8 +264,9 @@ export class API extends ParentAPI {`
`254`	`264`	`)`
`255`	`265`
`256`	`266`	`/**`
`257`		`- * Duplicate a Virtual MAC. Duplicate a Virtual MAC from a given Flexible IP`
`258`		`- * onto another attached on the same server.`
	`267`	`+ * Duplicate a virtual MAC address to another flexible IP. Duplicate a virtual`
	`268`	`+ * MAC address from a given flexible IP to another flexible IP attached to the`
	`269`	`+ * same server.`
`259`	`270`	`*`
`260`	`271`	`* @param request - The request {@link DuplicateMACAddrRequest}`
`261`	`272`	`* @returns A Promise of FlexibleIP`
`@@ -277,8 +288,9 @@ export class API extends ParentAPI {`
`277`	`288`	`)`
`278`	`289`
`279`	`290`	`/**`
`280`		`- * Move a virtual MAC. Move a Virtual MAC from a given Flexible IP onto`
`281`		`- * another Flexible IP.`
	`291`	`+ * Relocate an existing virtual MAC address to a different flexible IP.`
	`292`	`+ * Relocate a virtual MAC (Media Access Control) address from an existing`
	`293`	`+ * flexible IP to a different flexible IP.`
`282`	`294`	`*`
`283`	`295`	`* @param request - The request {@link MoveMACAddrRequest}`
`284`	`296`	`* @returns A Promise of FlexibleIP`
`@@ -300,7 +312,8 @@ export class API extends ParentAPI {`
`300`	`312`	`)`
`301`	`313`
`302`	`314`	`/**`
`303`		`- * Remove a virtual MAC from a Flexible IP.`
	`315`	`+ * Detach a given virtual MAC address from an existing flexible IP. Detach a`
	`316`	`+ * given MAC (Media Access Control) address from an existing flexible IP.`
`304`	`317`	`*`
`305`	`318`	`* @param request - The request {@link DeleteMACAddrRequest}`
`306`	`319`	`*/`