Updates the description of the Update mappings API

specification/indices/put_mapping/IndicesPutMappingRequest.ts

@@ -41,33 +41,17 @@ import { Dictionary, SingleKeyDictionary } from '@spec_utils/Dictionary'
 /**
  * Update field mappings.
  * Add new fields to an existing data stream or index.
- * You can also use this API to change the search settings of existing fields and add new properties to existing object fields.
- * For data streams, these changes are applied to all backing indices by default.
- *
- * **Add multi-fields to an existing field**
- *
- * Multi-fields let you index the same field in different ways.
- * You can use this API to update the fields mapping parameter and enable multi-fields for an existing field.
- * WARNING: If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field.
- * You can populate the new multi-field with the update by query API.
- *
- * **Change supported mapping parameters for an existing field**
- *
- * The documentation for each mapping parameter indicates whether you can update it for an existing field using this API.
- * For example, you can use the update mapping API to update the `ignore_above` parameter.
- *
- * **Change the mapping of an existing field**
- *
- * Except for supported mapping parameters, you can't change the mapping or field type of an existing field.
- * Changing an existing field could invalidate data that's already indexed.
- *
- * If you need to change the mapping of a field in a data stream's backing indices, refer to documentation about modifying data streams.
- * If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.
- *
- * **Rename a field**
- *
- * Renaming a field would invalidate data already indexed under the old field name.
- * Instead, add an alias field to create an alternate field name.
+ * You can use the update mapping API to:
+
+ * - Add a new field to an existing index
+ * - Update mappings for multiple indices in a single request
+ * - Add new properties to an object field
+ * - Enable multi-fields for an existing field
+ * - Update supported mapping parameters
+ * - Change a field's mapping using reindexing
+ * - Rename a field using a field alias
+ * 
+ * Learn how to use the update mapping API with practical examples in the [Update mapping API examples](https://www.elastic.co/docs//manage-data/data-store/mapping/update-mappings-examples) guide.
  * @rest_spec_name indices.put_mapping
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public