respond to review comments

rust/protocol/src/address.rs

@@ -3,11 +3,14 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 
-//! Where to send a [sealed_sender] message to.
+//! A normalized representation of an individual Signal client instance.
 
 // These are used in docstrings.
-#[allow(unused_imports)]
-use crate::sealed_sender::{self, UnidentifiedSenderMessageContent};
+#[cfg(doc)]
+use crate::{
+    sealed_sender::{self, UnidentifiedSenderMessageContent},
+    SignalMessage,
+};
 
 use std::fmt;
 
@@ -17,7 +20,7 @@ use std::fmt;
 /// Used in [ProtocolAddress].
 pub type DeviceId = u32;
 
-/// The target of an [UnidentifiedSenderMessageContent].
+/// Represents a unique Signal client instance as `(<user ID>, <device ID>)` pair.
 #[derive(Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
 pub struct ProtocolAddress {
     name: String,
@@ -37,7 +40,7 @@ impl ProtocolAddress {
 
     /// A unique identifier for the target user.
     ///
-    /// In the Signal app, this is currently a phone number.
+    /// In the Signal app, this is usually a UUID, although that may change in the future.
     #[inline]
     pub fn name(&self) -> &str {
         &self.name
@@ -47,9 +50,8 @@ impl ProtocolAddress {
     ///
     /// For example, if a user has set up Signal on both their phone and laptop, any
     /// [UnidentifiedSenderMessageContent] sent to the user will only go to a single
-    /// device. Handling this is part of the [Sesame] algorithm.
-    ///
-    /// [Sesame]: https://signal.org/docs/specifications/sesame/#assumptions
+    /// device. A single [SignalMessage] goes to a particular device, so when a user sends a message
+    /// to another user at all, they're actually sending a message to *every* device.
     #[inline]
     pub fn device_id(&self) -> DeviceId {
         self.device_id