fix review comments

rust/protocol/src/identity_key.rs

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 
-//! Wrappers over cryptographic primitives from [crate::curve] to represent [identity].
+//! Wrappers over cryptographic primitives from [`crate::curve`] to represent [identity].
 //!
 //! [identity]: https://en.wikipedia.org/wiki/Online_identity
 
@@ -12,9 +12,6 @@
 use crate::proto;
 use crate::{KeyPair, PrivateKey, PublicKey, Result, SignalProtocolError};
 
-#[cfg(doc)]
-use crate::{protocol::PreKeySignalMessage, state::SessionRecord, storage::IdentityKeyStore};
-
 use rand::{CryptoRng, Rng};
 use std::convert::TryFrom;
 
@@ -24,9 +21,9 @@ use prost::Message;
 const ALTERNATE_IDENTITY_SIGNATURE_PREFIX_1: &[u8] = &[0xFF; 32];
 const ALTERNATE_IDENTITY_SIGNATURE_PREFIX_2: &[u8] = b"Signal_PNI_Signature";
 
-/// The public identity of a user, used in [IdentityKeyStore].
+/// A public key that represents the identity of a user.
 ///
-/// Wrapper for [PublicKey].
+/// Wrapper for [`PublicKey`].
 #[derive(Debug, PartialOrd, Ord, PartialEq, Eq, Clone, Copy)]
 pub struct IdentityKey {
     public_key: PublicKey,
@@ -38,13 +35,13 @@ impl IdentityKey {
         Self { public_key }
     }
 
-    /// Return a public key representing the public identity.
+    /// Return the public key representing this identity.
     #[inline]
     pub fn public_key(&self) -> &PublicKey {
         &self.public_key
     }
 
-    /// Return an owned byte slice which can be deserialized with [Self::decode].
+    /// Return an owned byte slice which can be deserialized with [`Self::decode`].
     #[inline]
     pub fn serialize(&self) -> Box<[u8]> {
         self.public_key.serialize()
@@ -56,7 +53,10 @@ impl IdentityKey {
         Ok(Self { public_key: pk })
     }
 
-    /// Verify `signature` matches a provided identity key `other` (*not* `self`)!
+    /// Given a trusted identity `self`, verify that `other` represents the same user for the given
+    /// `signature`.
+    ///
+    /// `signature` must be calculated from [`IdentityKeyPair::sign_alternate_identity`].
     pub fn verify_alternate_identity(&self, other: &IdentityKey, signature: &[u8]) -> Result<bool> {
         self.public_key.verify_signature_for_multipart_message(
             &[
@@ -91,11 +91,7 @@ impl From<IdentityKey> for PublicKey {
 
 /// The private identity of a user.
 ///
-/// This cryptographic identity is used to sign pre-keys in [PreKeySignalMessage], to conceal
-/// sealed-sender [crate::sealed_sender::UnidentifiedSenderMessage]s, or to initiate the key
-/// derivation function for a [SessionRecord].
-///
-/// Also see [KeyPair].
+/// Can be converted to and from [`KeyPair`].
 #[derive(Copy, Clone)]
 pub struct IdentityKeyPair {
     identity_key: IdentityKey,
@@ -139,7 +135,7 @@ impl IdentityKeyPair {
         &self.private_key
     }
 
-    /// Return a byte slice which can later be deserialized with [Self::try_from].
+    /// Return a byte slice which can later be deserialized with [`Self::try_from`].
     pub fn serialize(&self) -> Box<[u8]> {
         let structure = proto::storage::IdentityKeyPairStructure {
             public_key: self.identity_key.serialize().to_vec(),
@@ -150,7 +146,7 @@ impl IdentityKeyPair {
         result.into_boxed_slice()
     }
 
-    /// Generate a signature for a provided identity key `other` (*not* `self`)!
+    /// Generate a signature claiming that `other` represents the same user as `self`.
     pub fn sign_alternate_identity<R: Rng + CryptoRng>(
         &self,
         other: &IdentityKey,