chore: Document our libolm pickling methods

matrix-org · Nov 30, 2022 · cbae68b · cbae68b
1 parent b8c0963
commit cbae68b
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 25 deletions.
diff --git a/src/megolm/group_session.rs b/src/megolm/group_session.rs
@@ -141,15 +141,11 @@ impl GroupSession {
         pickle.into()
     }
 
-    #[cfg(feature = "libolm-compat")]
-    pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
-        use libolm::Pickle;
-
-        use crate::utilities::pickle_libolm;
-
-        pickle_libolm::<Pickle>(self.into(), pickle_key)
-    }
-
+    /// Create a [`GroupSession`] object by unpickling a session pickle
+    /// in libolm legacy pickle format.
+    ///
+    /// Such pickles are encrypted and need to first be decrypted using
+    /// `pickle_key`.
     #[cfg(feature = "libolm-compat")]
     pub fn from_libolm_pickle(
         pickle: &str,
@@ -161,6 +157,24 @@ impl GroupSession {
 
         unpickle_libolm::<Pickle, _>(pickle, pickle_key, PICKLE_VERSION)
     }
+
+    /// Pickle an [`GroupSession`] into a libolm pickle format.
+    ///
+    /// This pickle can be restored using the
+    /// [`InboundGroupSession::from_libolm_pickle`] method, or can be used in
+    /// the [`libolm`] C library.
+    ///
+    /// The pickle will be encryptd using the pickle key.
+    ///
+    /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/
+    #[cfg(feature = "libolm-compat")]
+    pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
+        use libolm::Pickle;
+
+        use crate::utilities::pickle_libolm;
+
+        pickle_libolm::<Pickle>(self.into(), pickle_key)
+    }
 }
 
 /// A format suitable for serialization which implements [`serde::Serialize`]

diff --git a/src/megolm/inbound_group_session.rs b/src/megolm/inbound_group_session.rs
@@ -365,15 +365,11 @@ impl InboundGroupSession {
         Self::from(pickle)
     }
 
-    #[cfg(feature = "libolm-compat")]
-    pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
-        use libolm::Pickle;
-
-        use crate::utilities::pickle_libolm;
-
-        pickle_libolm::<Pickle>(self.into(), pickle_key)
-    }
-
+    /// Create a [`InboundGroupSession`] object by unpickling a session pickle
+    /// in libolm legacy pickle format.
+    ///
+    /// Such pickles are encrypted and need to first be decrypted using
+    /// `pickle_key`.
     #[cfg(feature = "libolm-compat")]
     pub fn from_libolm_pickle(
         pickle: &str,
@@ -385,6 +381,24 @@ impl InboundGroupSession {
 
         unpickle_libolm::<Pickle, _>(pickle, pickle_key, PICKLE_VERSION)
     }
+
+    /// Pickle an [`InboundGroupSession`] into a libolm pickle format.
+    ///
+    /// This pickle can be restored using the
+    /// [`InboundGroupSession::from_libolm_pickle`] method, or can be used in
+    /// the [`libolm`] C library.
+    ///
+    /// The pickle will be encryptd using the pickle key.
+    ///
+    /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/
+    #[cfg(feature = "libolm-compat")]
+    pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
+        use libolm::Pickle;
+
+        use crate::utilities::pickle_libolm;
+
+        pickle_libolm::<Pickle>(self.into(), pickle_key)
+    }
 }
 
 /// A format suitable for serialization which implements [`serde::Serialize`]

diff --git a/src/olm/account/mod.rs b/src/olm/account/mod.rs
@@ -357,6 +357,21 @@ impl Account {
         unpickle_libolm::<Pickle, _>(pickle, pickle_key, PICKLE_VERSION)
     }
 
+    /// Pickle an [`Account`] into a libolm pickle format.
+    ///
+    /// This pickle can be restored using the `[Account::from_libolm_pickle]`
+    /// method, or can be used in the [`libolm`] C library.
+    ///
+    /// The pickle will be encryptd using the pickle key.
+    ///
+    /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/
+    #[cfg(feature = "libolm-compat")]
+    pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
+        use self::libolm::Pickle;
+        use crate::utilities::pickle_libolm;
+        pickle_libolm::<Pickle>(self.into(), pickle_key)
+    }
+
     #[cfg(all(any(fuzzing, test), feature = "libolm-compat"))]
     pub fn from_decrypted_libolm_pickle(pickle: &[u8]) -> Result<Self, crate::LibolmPickleError> {
         use std::io::Cursor;
@@ -370,13 +385,6 @@ impl Account {
 
         pickle.try_into()
     }
-
-    #[cfg(feature = "libolm-compat")]
-    pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
-        use self::libolm::Pickle;
-        use crate::utilities::pickle_libolm;
-        pickle_libolm::<Pickle>(self.into(), pickle_key)
-    }
 }
 
 impl Default for Account {

diff --git a/src/olm/session/mod.rs b/src/olm/session/mod.rs
@@ -339,6 +339,14 @@ impl Session {
         unpickle_libolm::<Pickle, _>(pickle, pickle_key, libolm::PICKLE_VERSION)
     }
 
+    /// Pickle an [`Session`] into a libolm pickle format.
+    ///
+    /// This pickle can be restored using the [`Session::from_libolm_pickle`]
+    /// method, or can be used in the [`libolm`] C library.
+    ///
+    /// The pickle will be encryptd using the pickle key.
+    ///
+    /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/
     #[cfg(feature = "libolm-compat")]
     pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result<String, crate::LibolmPickleError> {
         use self::libolm::Pickle;