Add summaries for machine learning APIs

specification/ml/close_job/MlCloseJobRequest.ts

@@ -22,7 +22,6 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Closes one or more anomaly detection jobs.
  * A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.
  * When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.
  * If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.
@@ -32,6 +31,7 @@ import { Duration } from '@_types/Time'
  * @availability serverless stability=stable visibility=public
  * @cluster_privileges manage_ml
  * @doc_id ml-close-job
+ * @doc_summary Close one or more anomaly detection jobs.
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/ml/delete_job/MlDeleteJobRequest.ts

@@ -21,18 +21,19 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Deletes an anomaly detection job.
- *
+ * Before you can delete a job, you must close it (unless you specify the `force` query parameter).
  * All job configuration, model state and results are deleted.
- * It is not currently possible to delete multiple jobs using wildcards or a
- * comma separated list. If you delete a job that has a datafeed, the request
- * first tries to delete the datafeed. This behavior is equivalent to calling
- * the delete datafeed API with the same timeout and force parameters as the
- * delete job request.
+ * Deleting an anomaly detection job must be done via this API only.
+ * Do not delete the job directly from the `.ml-*` indices using the Elasticsearch delete document API.
+ * When Elasticsearch security features are enabled, make sure no write privileges are granted to anyone over the `.ml-*` indices.
+ * It is not currently possible to delete multiple jobs using wildcards or a comma separated list.
+ * If you delete a job that has a datafeed, the request first tries to delete the datafeed.
+ * This behavior is equivalent to calling the delete datafeed API with the same timeout and force parameters as the delete job request.
  * @rest_spec_name ml.delete_job
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @cluster_privileges manage_ml
+ * @doc_summary Delete an anomaly detection job.
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/ml/open_job/MlOpenJobRequest.ts

@@ -22,18 +22,16 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Opens one or more anomaly detection jobs.
- * An anomaly detection job must be opened in order for it to be ready to
- * receive and analyze data. It can be opened and closed multiple times
- * throughout its lifecycle.
+ * An anomaly detection job must be opened in order for it to be ready to receive and analyze data.
+ * It can be opened and closed multiple times throughout its lifecycle.
  * When you open a new job, it starts with an empty model.
- * When you open an existing job, the most recent model state is automatically
- * loaded. The job is ready to resume its analysis from where it left off, once
- * new data is received.
+ * When you open an existing job, the most recent model state is automatically loaded.
+ * The job is ready to resume its analysis from where it left off, once new data is received.
  * @rest_spec_name ml.open_job
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @cluster_privileges manage_ml
+ * @doc_summary Open one or more anomaly detection jobs.
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/ml/put_job/MlPutJobRequest.ts

@@ -28,12 +28,15 @@ import { Duration } from '@_types/Time'
 import { DatafeedConfig } from '@ml/_types/Datafeed'
 
 /**
- * Instantiates an anomaly detection job. If you include a `datafeed_config`, you must have read index privileges on the source index.
+ * If you include a `datafeed_config`, you must have read index privileges on the source index.
+ * You must use Kibana or this API to create an anomaly detection job. Do not put a job directly to the `.ml-config` index using the Elasticsearch index API.
+ * If Elasticsearch security features are enabled, do not give users write privileges on the `.ml-config` index.
  * @rest_spec_name ml.put_job
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @index_privileges read
  * @cluster_privileges manage_ml
+ * @doc_summary Create an anomaly detection job. 
  */
 export interface Request extends RequestBase {
   path_parts: {