[DOCS] Identify informational ML properties (elastic/x-pack-elasticsearch#3773)

Original commit: elastic/x-pack-elasticsearch@cb310b360d

docs/en/rest-api/ml/datafeedresource.asciidoc

@@ -9,7 +9,6 @@ A {dfeed} resource has the following properties:
   Support for aggregations is limited and should only be used with
   low cardinality data. For more information, see
   {xpack-ref}/ml-configuring-aggregation.html[Aggregating Data for Faster Performance].
-//<<ml-configuring-aggregation>>.
 
 `chunking_config`::
   (object) Specifies how data searches are split into time chunks.
@@ -18,6 +17,8 @@ A {dfeed} resource has the following properties:
 
 `datafeed_id`::
  (string) A numerical character string that uniquely identifies the {dfeed}.
+ This property is informational; you cannot change the identifier for existing
+ {dfeeds}.
 
 `frequency`::
   (time units) The interval at which scheduled queries are made while the
@@ -43,7 +44,7 @@ A {dfeed} resource has the following properties:
   example, if data from 10:04 a.m. might not be searchable in {es} until
   10:06 a.m., set this property to 120 seconds. The default value is randomly
   selected between `60s` and `120s`. This randomness improves the query
-  performance when there are multiple jobs running on the same node. 
+  performance when there are multiple jobs running on the same node.
 
 `script_fields`::
   (object) Specifies scripts that evaluate custom expressions and returns
@@ -88,7 +89,8 @@ A chunking configuration object has the following properties:
 ==== {dfeed-cap} Counts
 
 The get {dfeed} statistics API provides information about the operational
-progress of a {dfeed}. For example:
+progress of a {dfeed}. All of these properties are informational; you cannot
+update their values:
 
 `assignment_explanation`::
   (string) For started {dfeeds} only, contains messages relating to the

docs/en/rest-api/ml/jobresource.asciidoc

@@ -26,7 +26,8 @@ so do not set the `background_persist_interval` value too low.
 --
 
 `create_time`::
-  (string) The time the job was created. For example, `1491007356077`.
+  (string) The time the job was created. For example, `1491007356077`. This
+  property is informational; you cannot change its value.
 
 `custom_settings`::
   (object) Advanced configuration option. Contains custom meta data about the
@@ -47,7 +48,8 @@ so do not set the `background_persist_interval` value too low.
 
 `finished_time`::
   (string) If the job closed or failed, this is the time the job finished,
-  otherwise it is `null`.
+  otherwise it is `null`. This property is informational; you cannot change its
+  value.
 
 `groups`::
   (array of strings) A list of job groups.  A job can belong to no groups or
@@ -56,7 +58,8 @@ so do not set the `background_persist_interval` value too low.
 `job_id`::
   (string) The unique identifier for the job. This identifier can contain
   lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It
-  must start and end with alphanumeric characters.
+  must start and end with alphanumeric characters. This property is
+  informational; you cannot change the identifier for existing jobs.
 
 `job_type`::
   (string) Reserved for future use, currently set to `anomaly_detector`.
@@ -70,8 +73,9 @@ so do not set the `background_persist_interval` value too low.
 
 `model_snapshot_id`::
   (string) A numerical character string that uniquely identifies the model
-  snapshot. For example, `1491007364`.
-  For more information about model snapshots, see <<ml-snapshot-resource>>.
+  snapshot. For example, `1491007364`. This property is informational; you
+  cannot change its value. For more information about model snapshots, see
+  <<ml-snapshot-resource>>.
 
 `model_snapshot_retention_days`::
   (long) The time in days that model snapshots are retained for the job.
@@ -109,7 +113,6 @@ An analysis configuration object has the following properties:
   `by_field_name`, `over_field_name`, or `partition_field_name` to the keyword
   `mlcategory`. For more information, see
   {xpack-ref}/ml-configuring-categories.html[Categorizing Log Messages].
-//<<ml-configuring-categories>>.
 
 `categorization_filters`::
   (array of strings) If `categorization_field_name` is specified,
@@ -199,14 +202,8 @@ function.
 
 --
 
-////
-LEAVE UNDOCUMENTED
-`overlapping_buckets`::
- (boolean) If set to `true`, an additional analysis occurs that runs out of phase by half a bucket length.
- This requires more system resources and enhances detection of anomalies that span bucket boundaries.
-`use_per_partition_normalization`::
-  () TBD
-////
+After you create a job, you cannot change the analysis configuration object; all
+the properties are informational.
 
 [float]
 [[ml-detectorconfig]]
@@ -250,7 +247,6 @@ NOTE: The `field_name` cannot contain double quotes or backslashes.
   (string) The analysis function that is used.
   For example, `count`, `rare`, `mean`, `min`, `max`, and `sum`. For more
   information, see {xpack-ref}/ml-functions.html[Function Reference].
-//<<ml-functions>>.
 
 `over_field_name`::
   (string) The field used to split the data.
@@ -273,11 +269,9 @@ is different from one named 'bytes'.
 
 --
 
-////
-LEAVE UNDOCUMENTED
- `rules`::
-  (array) TBD
-////
+After you create a job, the only property you can change in the detector
+configuration object is the `detector_description`; all other properties are
+informational.
 
 [float]
 [[ml-datadescription]]

docs/en/rest-api/ml/resultsresource.asciidoc

@@ -38,8 +38,6 @@ identified. These are only applicable for jobs that are configured to analyze
 unstructured log data using categorization. These results do not contain a
 timestamp or any calculated scores. For more information, see
 {xpack-ref}/ml-configuring-categories.html[Categorizing Log Messages].
-//<<ml-configuring-categories>>.
-
 
 * <<ml-results-buckets,Buckets>>
 * <<ml-results-influencers,Influencers>>
@@ -47,6 +45,9 @@ timestamp or any calculated scores. For more information, see
 * <<ml-results-categories,Categories>>
 * <<ml-results-overall-buckets,Overall Buckets>>
 
+NOTE: All of these resources and properties are informational; you cannot
+change their values.
+
 [float]
 [[ml-results-buckets]]
 ==== Buckets

docs/en/rest-api/ml/snapshotresource.asciidoc

@@ -13,7 +13,6 @@ When choosing a new value, consider the following:
 * Persistence enables resilience in the event of a system failure.
 * Persistence enables snapshots to be reverted.
 * The time taken to persist a job is proportional to the size of the model in memory.
-//* The smallest allowed value is 3600 (1 hour).
 
 A model snapshot resource has the following properties:
 
@@ -21,7 +20,8 @@ A model snapshot resource has the following properties:
   (string) An optional description of the job.
 
 `job_id`::
-  (string) A numerical character string that uniquely identifies the job that the snapshot was created for.
+  (string) A numerical character string that uniquely identifies the job that
+  the snapshot was created for.
 
 `latest_record_time_stamp`::
   (date) The timestamp of the latest processed record.
@@ -49,6 +49,9 @@ A model snapshot resource has the following properties:
 `timestamp`::
   (date) The creation timestamp for the snapshot.
 
+NOTE: All of these properties are informational with the exception of
+`description` and `retain`.
+
 [float]
 [[ml-snapshot-stats]]
 ==== Model Size Statistics
@@ -93,3 +96,5 @@ The `model_size_stats` object has the following properties:
 
 `total_partition_field_count`::
   (long) The number of _partition_ field values analyzed.
+
+NOTE: All of these properties are informational; you cannot change their values.