doc: Clarify the behaviour of Vec<T> from JS to Rust.

CHANGELOG.md

@@ -14,10 +14,11 @@
     `OlmMachine.initFromStore`.
     ([#84](https://github.com/matrix-org/matrix-rust-sdk-crypto-wasm/pull/84))
 
--   Functions/methods that take a JavaScript `Array` as argument now delete the
-    array's items once their return, for example `Device::requestVerification`,
-    `OlmMachine::updateTrackedUsers`, `OlmMachine::shareRoomKey`,
-    `OlmMachine::queryKeysForUsers`, `OlmMachine:getMissingSessions` and so on.
+**BREAKING CHANGES**
+
+-   Functions/methods that take a JavaScript `Array` as argument now invalidate the
+    items within that array so that they cannot be re-used as soon as
+    they are received by the functions/methods. See the patch for affected methods.
     ([#82](https://github.com/matrix-org/matrix-rust-sdk-crypto-wasm/pull/82/))
 
 -   Update `wasm-bindgen` to 0.2.89. It allows to remove the `downcast` method.

src/device.rs

@@ -23,6 +23,8 @@ impl_from_to_inner!(matrix_sdk_crypto::Device => Device);
 impl Device {
     /// Request an interactive verification with this device.
     ///
+    /// Items inside `methods` will be invalidated by this method.
+    ///
     /// Returns a Promise for a 2-element array `[VerificationRequest,
     /// ToDeviceRequest]`.
     #[wasm_bindgen(js_name = "requestVerification")]

src/identities.rs

@@ -56,6 +56,8 @@ impl OwnUserIdentity {
     }
 
     /// Send a verification request to our other devices.
+    ///
+    /// Items inside `methods` will be invalidated by this method.
     #[wasm_bindgen(js_name = "requestVerification")]
     pub fn request_verification(
         &self,
@@ -158,6 +160,8 @@ impl UserIdentity {
 
     /// Create a `VerificationRequest` object after the verification
     /// request content has been sent out.
+    ///
+    /// Items inside `methods` will be invalidated by this method.
     #[wasm_bindgen(js_name = "requestVerification")]
     pub fn request_verification(
         &self,
@@ -185,6 +189,8 @@ impl UserIdentity {
     ///
     /// After the content has been sent out a VerificationRequest can be started
     /// with the `request_verification` method.
+    ///
+    /// Items inside `methods` will be invalidated by this method.
     #[wasm_bindgen(js_name = "verificationRequestContent")]
     pub fn verification_request_content(
         &self,

src/libolm_migration.rs

@@ -222,10 +222,10 @@ impl Migration {
     ///
     /// # Arguments
     ///
-    /// * `sessions` - An `Array` of {@link PickledSession}s to import.
+    /// * `sessions` - An `Array` of {@link PickledSession}s to import. Items
+    ///   inside `sessions` are going to be invalidated by this method.
     /// * `pickle_key` - The libolm pickle key that was used to pickle the olm
-    ///   session objects. Items inside `sessions` are going to be deleted on
-    ///   the JS part after the function returns.
+    ///   session objects.
     /// * `store_handle` - A connection to the CryptoStore which will be used to
     ///   store the vodozemac data.
     #[wasm_bindgen(js_name = "migrateOlmSessions")]
@@ -368,8 +368,8 @@ impl Migration {
     /// # Arguments
     ///
     /// * `sessions` - An `Array` of {@link PickledInboundGroupSession}s to
-    ///   import. Items inside `sessions` are going to be deleted on the JS part
-    ///   after the function returns.
+    ///   import. Items inside `sessions` are going to be invalidated by this
+    ///   method.
     /// * `pickle_key` - The libolm pickle key that was used to pickle the
     ///   megolm session objects.
     /// * `store_handle` - A connection to the CryptoStore which will be used to

src/machine.rs

@@ -227,8 +227,8 @@ impl OlmMachine {
     ///
     /// Users that were already in the list are unaffected.
     ///
-    /// Items inside `users` are going to be deleted on the JS part after the
-    /// function returns. Be careful to not used `users` after that.
+    /// Items inside `users` will be invalidated by this method. Be careful to
+    /// not used `UserId`s after this method has been called.
     #[wasm_bindgen(js_name = "updateTrackedUsers")]
     pub fn update_tracked_users(&self, users: Vec<identifiers::UserId>) -> Promise {
         let users = users.iter().map(|user| user.inner.clone()).collect::<Vec<_>>();
@@ -639,8 +639,8 @@ impl OlmMachine {
     ///
     /// Returns an array of `ToDeviceRequest`s.
     ///
-    /// Items inside `users` are going to be deleted on the JS part after the
-    /// function returns. Be careful to not used `users` after that.
+    /// Items inside `users` will be invalidated by this method. Be careful to
+    /// not used `UserId`s after this method has been called.
     #[wasm_bindgen(js_name = "shareRoomKey")]
     pub fn share_room_key(
         &self,
@@ -680,8 +680,8 @@ impl OlmMachine {
     /// Returns a `KeysQueryRequest` object. The response of the request should
     /// be passed to the `OlmMachine` with the `mark_request_as_sent`.
     ///
-    /// Items inside `users` are going to be deleted on the JS part after the
-    /// function returns. Be careful to not used `users` after that.
+    /// Items inside `users` will be invalidated by this method. Be careful to
+    /// not used `UserId`s after this method has been called.
     #[wasm_bindgen(js_name = "queryKeysForUsers")]
     pub fn query_keys_for_users(
         &self,
@@ -721,8 +721,8 @@ impl OlmMachine {
     /// we lack a session with one of their devices. This can be an
     /// empty iterator when calling this method between sync requests.
     ///
-    /// Items inside `users` are going to be deleted on the JS part after the
-    /// function returns. Be careful to not used `users` after that.
+    /// Items inside `users` will be invalidated by this method. Be careful to
+    /// not used `UserId`s after this method has been called.
     #[wasm_bindgen(js_name = "getMissingSessions")]
     pub fn get_missing_sessions(&self, users: Vec<identifiers::UserId>) -> Promise {
         let users = users.iter().map(|user| user.inner.clone()).collect::<Vec<_>>();

src/sync_events.rs

@@ -18,6 +18,9 @@ impl DeviceLists {
     /// Create an empty `DeviceLists`.
     ///
     /// `changed` and `left` must be an array of `UserId`.
+    ///
+    /// Items inside `changed` and `left` will be invalidated by this method. Be
+    /// careful to not used `UserId`s after this method has been called.
     #[wasm_bindgen(constructor)]
     pub fn new(
         changed: Option<Vec<identifiers::UserId>>,

src/verification.rs

@@ -984,6 +984,8 @@ impl VerificationRequest {
     /// supported by us. Items inside `methods` are going to be deleted on the
     /// JS part after the function returns.
     ///
+    /// Items inside `methods` will be invalidated by this method.
+    ///
     /// It returns either a `ToDeviceRequest`, a `RoomMessageRequest`
     /// or `undefined`.
     #[wasm_bindgen(js_name = "acceptWithMethods")]