test: add examples for the new builder

testing/matrix-sdk-test/src/test_json/keys_query_sets.rs

@@ -21,6 +21,71 @@ use crate::{
 
 /// A test helper for building test data sets for `/keys/query` response objects
 /// ([`KeyQueryResponse`]).
+///
+/// # Examples
+///
+/// A simple case with no cross-signing identity and a single device:
+///
+/// ```
+/// # use ruma::{device_id, owned_user_id};
+/// # use vodozemac::{Curve25519PublicKey, Ed25519SecretKey};
+/// # use matrix_sdk_test::test_json::keys_query_sets::KeyQueryResponseTemplate;
+///
+/// let pub_curve_key = "PBo2nKbink/HxgzMrBftGPogsD0d47LlIMsViTpCRn4";
+/// let ed25519_key = "yzj53Kccfqx2yx9lcTwaRfPZX+7jU19harsDWWu5YnM";
+///
+/// let builder = KeyQueryResponseTemplate::new(owned_user_id!("@alice:localhost"))
+///     .with_device(
+///         device_id!("TESTDEVICE"),
+///         &Curve25519PublicKey::from_base64(pub_curve_key).unwrap(),
+///         &Ed25519SecretKey::from_base64(ed25519_key).unwrap(),
+///         false,
+///     );
+///
+/// let response = builder.build_response();
+/// ```
+///
+///
+/// A more complex case, with cross-signing keys and a signed device:
+///
+/// ```
+/// # use ruma::{device_id, owned_user_id, user_id};
+/// # use vodozemac::{Curve25519PublicKey, Ed25519SecretKey};
+/// # use matrix_sdk_test::test_json::keys_query_sets::KeyQueryResponseTemplate;
+///
+/// // Private cross-signing keys
+/// let master_key = "QGZo39k199RM0NYvPvFNXBspc5llftHWKKHqEi25q0U";
+/// let ssk = "0ES1HO5VXpy/BsXxadwsk6QcwH/ci99KkV9ZlPakHlU";
+/// let usk = "vSdfrHJO8sZH/54r1uCg8BE0CdcDVGkPQNOu7Ej8BBs";
+///
+/// // Device keys
+/// let pub_curve_key = "PBo2nKbink/HxgzMrBftGPogsD0d47LlIMsViTpCRn4";
+/// let ed25519_key = "yzj53Kccfqx2yx9lcTwaRfPZX+7jU19harsDWWu5YnM";
+///
+/// let other_user_usk = "zQSosK46giUFs2ACsaf32bA7drcIXbmViyEt+TLfloI";
+///
+/// let builder = KeyQueryResponseTemplate::new(owned_user_id!("@me:localhost"))
+///     // add cross-signing keys
+///     .with_cross_signing_keys(
+///         Ed25519SecretKey::from_base64(master_key).unwrap(),
+///         Ed25519SecretKey::from_base64(ssk).unwrap(),
+///         Ed25519SecretKey::from_base64(usk).unwrap(),
+///     )
+///     // add verification from another user
+///     .with_user_verification_signature(
+///         user_id!("@them:localhost"),
+///         &Ed25519SecretKey::from_base64(other_user_usk).unwrap(),
+///     )
+///     // add signed device
+///     .with_device(
+///         device_id!("SECUREDEVICE"),
+///         &Curve25519PublicKey::from_base64(pub_curve_key).unwrap(),
+///         &Ed25519SecretKey::from_base64(ed25519_key).unwrap(),
+///         true,
+///     );
+///
+/// let response = builder.build_response();
+/// ```
 pub struct KeyQueryResponseTemplate {
     /// The User ID of the user that this test data is about.
     user_id: OwnedUserId,