SDK: generate class and method comments (#41)

Author: fjakobs

packages/databricks-sdk-js/src/apis/cluster.ts

@@ -751,6 +751,14 @@ export class ClusterService {
         this.client = client;
     }
 
+    /**
+     * Returns information about all pinned clusters, currently active clusters, up to 70 of the most
+     * recently terminated interactive clusters in the past 7 days, and up to 30 of the most recently
+     * terminated job clusters in the past 7 days. For example, if there is 1 pinned cluster, 4 active
+     * clusters, 45 terminated interactive clusters in the past 7 days, and 50 terminated job clusters
+     * in the past 7 days, then this API returns the 1 pinned cluster, 4 active clusters, all 45
+     * terminated interactive clusters, and the 30 most recently terminated job clusters.
+     */
     async listClusters(
         request: ListClustersRequest
     ): Promise<ListClustersResponse> {
@@ -761,6 +769,51 @@ export class ClusterService {
         )) as ListClustersResponse;
     }
 
+    /**
+     * Creates a new Spark cluster. This method will acquire new instances from the cloud provider
+     * if necessary. This method is asynchronous; the returned ``cluster_id`` can be used to poll the
+     * cluster status. When this method returns, the cluster will be in
+     * a ``PENDING`` state. The cluster will be usable once it enters a ``RUNNING`` state.
+     * Note: Databricks may not be able to acquire some of the requested nodes, due to cloud provider
+     * limitations (account limits, spot price, ...) or transient network issues. If Databricks
+     * acquires at least 85% of the requested on-demand nodes, cluster creation will succeed.
+     * Otherwise the cluster will terminate with an informative error message.
+     *
+     * An example request:
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_name": "my-cluster",
+     *       "spark_version": "2.0.x-scala2.10",
+     *       "node_type_id": "r3.xlarge",
+     *       "spark_conf": {
+     *         "spark.speculation": true
+     *       },
+     *       "aws_attributes": {
+     *         "availability": "SPOT",
+     *         "zone_id": "us-west-2a"
+     *       },
+     *       "num_workers": 25
+     *     }
+     *
+     *
+     *
+     * See below as an example for an autoscaling cluster. Note that this cluster will start with
+     * `2` nodes, the minimum.
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_name": "autoscaling-cluster",
+     *       "spark_version": "2.0.x-scala2.10",
+     *       "node_type_id": "r3.xlarge",
+     *       "autoscale" : {
+     *         "min_workers": 2,
+     *         "max_workers": 50
+     *       }
+     *     }
+     */
     async create(
         request: CreateClusterRequest
     ): Promise<CreateClusterResponse> {
@@ -771,6 +824,23 @@ export class ClusterService {
         )) as CreateClusterResponse;
     }
 
+    /**
+     * Starts a terminated Spark cluster given its id. This works similar to `createCluster` except:
+     *   - The previous cluster id and attributes are preserved.
+     *   - The cluster starts with the last specified cluster size.
+     *      - If the previous cluster was an autoscaling cluster, the current cluster starts with
+     *        the minimum number of nodes.
+     *   - If the cluster is not currently in a ``TERMINATED`` state, nothing will happen.
+     *   - Clusters launched to run a job cannot be started.
+     *
+     * An example request:
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_id": "1202-211320-brick1"
+     *     }
+     */
     async start(request: StartClusterRequest): Promise<StartClusterResponse> {
         return (await this.client.request(
             "/api/2.0/clusters/start",
@@ -779,6 +849,9 @@ export class ClusterService {
         )) as StartClusterResponse;
     }
 
+    /**
+     * Returns the list of available Spark versions. These versions can be used to launch a cluster.
+     */
     async listSparkVersions(
         request: GetSparkVersionsRequest
     ): Promise<GetSparkVersionsResponse> {
@@ -789,6 +862,19 @@ export class ClusterService {
         )) as GetSparkVersionsResponse;
     }
 
+    /**
+     * Terminates a Spark cluster given its id. The cluster is removed asynchronously. Once the
+     * termination has completed, the cluster will be in a ``TERMINATED`` state. If the cluster is
+     * already in a ``TERMINATING`` or ``TERMINATED`` state, nothing will happen.
+     *
+     * An example request:
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_id": "1202-211320-brick1"
+     *     }
+     */
     async delete(
         request: DeleteClusterRequest
     ): Promise<DeleteClusterResponse> {
@@ -799,6 +885,19 @@ export class ClusterService {
         )) as DeleteClusterResponse;
     }
 
+    /**
+     * Permanently deletes a Spark cluster. This cluster is terminated and resources are
+     * asynchronously removed. In addition, users will no longer see permanently deleted clusters in
+     * the cluster list, and API users can no longer perform any action on permanently deleted
+     * clusters.
+     * An example request:
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_id": "1202-211320-brick1"
+     *     }
+     */
     async permanentDelete(
         request: PermanentDeleteClusterRequest
     ): Promise<PermanentDeleteClusterResponse> {
@@ -809,6 +908,18 @@ export class ClusterService {
         )) as PermanentDeleteClusterResponse;
     }
 
+    /**
+     * Restarts a Spark cluster given its id. If the cluster is not currently in a ``RUNNING`` state,
+     * nothing will happen.
+     *
+     * An example request:
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_id": "1202-211320-brick1"
+     *     }
+     */
     async restart(
         request: RestartClusterRequest
     ): Promise<RestartClusterResponse> {
@@ -819,6 +930,19 @@ export class ClusterService {
         )) as RestartClusterResponse;
     }
 
+    /**
+     * Resizes a cluster to have a desired number of workers. This will fail unless the cluster
+     * is in a ``RUNNING`` state.
+     *
+     * An example request:
+     *
+     * .. code::
+     *
+     *     {
+     *       "cluster_id": "1202-211320-brick1",
+     *       "num_workers": 30
+     *     }
+     */
     async resize(
         request: ResizeClusterRequest
     ): Promise<ResizeClusterResponse> {
@@ -829,6 +953,29 @@ export class ClusterService {
         )) as ResizeClusterResponse;
     }
 
+    /**
+     * Edits the configuration of a cluster to match the provided attributes and size.
+     *
+     * A cluster can be edited if it is in a ``RUNNING`` or ``TERMINATED`` state.
+     * If a cluster is edited while in a ``RUNNING`` state, it will be restarted
+     * so that the new attributes can take effect. If a cluster is edited while in a ``TERMINATED``
+     * state, it will remain ``TERMINATED``. The next time it is started using the ``clusters/start``
+     * API, the new attributes will take effect. An attempt to edit a cluster in any other state will
+     * be rejected with an ``INVALID_STATE`` error code.
+     *
+     * Clusters created by the Databricks Jobs service cannot be edited.
+     *
+     * An example request:
+     *
+     * .. code::
+     *
+     *    {
+     *      "cluster_id": "1202-211320-brick1",
+     *      "num_workers": 10,
+     *      "spark_version": "3.3.x-scala2.11",
+     *      "node_type_id": "i3.2xlarge"
+     *    }
+     */
     async edit(request: EditClusterRequest): Promise<EditClusterResponse> {
         return (await this.client.request(
             "/api/2.0/clusters/edit",
@@ -837,6 +984,9 @@ export class ClusterService {
         )) as EditClusterResponse;
     }
 
+    /**
+     * Public version of editClusterOwner, allowing admins to change cluster owner
+     */
     async changeClusterOwner(
         request: ChangeClusterOwnerRequest
     ): Promise<ChangeClusterOwnerResponse> {
@@ -847,6 +997,15 @@ export class ClusterService {
         )) as ChangeClusterOwnerResponse;
     }
 
+    /**
+     * Retrieves the information for a cluster given its identifier.
+     * Clusters can be described while they are running, or up to 60 days after they are terminated.
+     *
+     * An example request:
+     *
+     *
+     * ``/clusters/get?cluster_id=1202-211320-brick1``
+     */
     async get(request: GetClusterRequest): Promise<GetClusterResponse> {
         return (await this.client.request(
             "/api/2.0/clusters/get",
@@ -855,6 +1014,16 @@ export class ClusterService {
         )) as GetClusterResponse;
     }
 
+    /**
+     * Pinning a cluster ensures that the cluster will always be returned by the ListClusters API.
+     * Pinning a cluster that is already pinned will have no effect.
+     * This API can only be called by workspace admins.
+     *
+     * An example request:
+     *
+     *
+     * ``/clusters/pin?cluster_id=1202-211320-brick1``
+     */
     async pin(request: PinClusterRequest): Promise<PinClusterResponse> {
         return (await this.client.request(
             "/api/2.0/clusters/pin",
@@ -863,6 +1032,16 @@ export class ClusterService {
         )) as PinClusterResponse;
     }
 
+    /**
+     * Unpinning a cluster will allow the cluster to eventually be removed from the ListClusters API.
+     * Unpinning a cluster that is not pinned will have no effect.
+     * This API can only be called by workspace admins.
+     *
+     * An example request:
+     *
+     *
+     * ``/clusters/unpin?cluster_id=1202-211320-brick1``
+     */
     async unpin(request: UnpinClusterRequest): Promise<UnpinClusterResponse> {
         return (await this.client.request(
             "/api/2.0/clusters/unpin",
@@ -871,6 +1050,9 @@ export class ClusterService {
         )) as UnpinClusterResponse;
     }
 
+    /**
+     * Returns a list of supported Spark node types. These node types can be used to launch a cluster.
+     */
     async listNodeTypes(
         request: ListNodeTypesRequest
     ): Promise<ListNodeTypesResponse> {
@@ -881,6 +1063,10 @@ export class ClusterService {
         )) as ListNodeTypesResponse;
     }
 
+    /**
+     * Returns a list of availability zones where clusters can be created in (ex: us-west-2a).
+     * These zones can be used to launch a cluster.
+     */
     async listAvailableZones(
         request: ListAvailableZonesRequest
     ): Promise<ListAvailableZonesResponse> {
@@ -891,6 +1077,54 @@ export class ClusterService {
         )) as ListAvailableZonesResponse;
     }
 
+    /**
+     * Retrieves a list of events about the activity of a cluster.
+     * This API is paginated. If there are more events to read, the response includes all the
+     * parameters necessary to request the next page of events.
+     *
+     * An example request:
+     *
+     *  ``/clusters/events?cluster_id=1202-211320-brick1``
+     *
+     * An example response:
+     *
+     * {
+     *  "events": [
+     *    {
+     *      "cluster_id": "1202-211320-brick1",
+     *      "timestamp": 1509572145487,
+     *      "event_type": "RESTARTING",
+     *      "event_details": {
+     *        "username": "admin"
+     *      }
+     *    },
+     *    ...
+     *    {
+     *      "cluster_id": "1202-211320-brick1",
+     *      "timestamp": 1509505807923,
+     *      "event_type": "TERMINATING",
+     *      "event_details": {
+     *        "termination_reason": {
+     *          "code": "USER_REQUEST",
+     *          "parameters": [
+     *            "username": "admin"
+     *          ]
+     *      }
+     *    }
+     *  ],
+     *  "next_page": {
+     *    "cluster_id": "1202-211320-brick1",
+     *    "end_time": 1509572145487,
+     *    "order": "DESC",
+     *    "offset": 50
+     *  },
+     *  "total_count": 303
+     * }
+     *
+     * Example request to retrieve the next page of events
+     *
+     *  ``/clusters/events?cluster_id=1202-211320-brick1&end_time=1509572145487&order=DESC&offset=50``
+     */
     async getEvents(request: GetEventsRequest): Promise<GetEventsResponse> {
         return (await this.client.request(
             "/api/2.0/clusters/events",