Update DataCollection changeId method: DHX-5162

docs/data_collection/api/datacollection_changeid_method.md

@@ -8,16 +8,34 @@ description: You can explore the changeId method of DataCollection in the docume
 
 @short: changes the id of an element of a data collection
 
-@signature: {'changeId(id: string | number, newId?: string | number, silent?: boolean): void;'}
+#### Usage
+
+~~~ts
+type Id = string | number;
+changeId(id: Id, newId?: Id, silent?: boolean): Id;
+~~~
 
 @params:
-- `id: string | number` - the old id of an item
-- `newId: string | number` - the new id; auto-generated if not set
-- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events; otherwise, *false*
+- `id: Id` - the old id of an item
+- `newId?: Id` - optional, the new id; auto-generated if not set
+- `silent?: boolean` - optional, if set to *true*, the method will not trigger the [change](data_collection/api/datacollection_change_event.md) event; otherwise, *false*
+
+@returns:
+The new id of the item, or the original id if the change was rejected.
 
 @example:
-component.data.changeId("1", "22");
+// changing the id of an item
+component.data.changeId("1", "22"); // -> "22"
+
+// the new id is generated automatically
+const generatedId = component.data.changeId("22");
+
+// changing the id without triggering the change event
+component.data.changeId(generatedId, "33", true);
 
 @descr:
 
-@changelog: added in v6.4
+@changelog:
+
+- The return value was added in v9.4
+- The method was added in v6.4