add missing docs warning

fix uuid deps

add doctest for `ProtocolAddress::new()`!

rust/protocol/Cargo.toml

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2020 Signal Messenger, LLC.
+# Copyright (C) 2020-2021 Signal Messenger, LLC.
 # SPDX-License-Identifier: AGPL-3.0-only
 #
 
@@ -27,7 +27,10 @@ x25519-dalek = "1.0"
 hex = "0.4"
 log = "0.4"
 num_enum = "0.5.1"
-uuid = "0.8"
+
+[dependencies.uuid]
+features = ["v4"]
+version = "0.8"
 
 [dependencies.curve25519-dalek]
 features = ["serde", "alloc"]
@@ -46,6 +49,10 @@ nightly = ["curve25519-dalek/nightly"]
 criterion = "0.3"
 futures = "0.3.7"
 
+[dev-dependencies.uuid]
+features = ["v4"]
+version = "0.8"
+
 [build-dependencies]
 prost-build = "0.7"
 

rust/protocol/src/address.rs

@@ -3,6 +3,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 
+#![warn(missing_docs)]
+
 //! A normalized representation of an individual Signal client instance.
 
 #[cfg(doc)]
@@ -30,6 +32,24 @@ impl ProtocolAddress {
     /// user.
     /// - Each Signal client instance then has its own `device_id`, which must be unique among
     ///   all clients for that user.
+    ///
+    ///```
+    /// use libsignal_protocol::{DeviceId, ProtocolAddress};
+    /// # use rand::{Rng, rngs::OsRng};
+    /// # use uuid::Uuid;
+    ///
+    /// // This is a unique id for some user, typically a UUID.
+    /// let user_id: String;
+    /// # user_id = Uuid::new_v4().to_hyphenated().to_string();
+    /// // This device id would be associated with a particular client instance representing
+    /// // the user.
+    /// let device_id: u32;
+    /// # device_id = (&mut OsRng).gen();
+    /// let address = ProtocolAddress::new(user_id.clone(), device_id.into());
+    ///
+    /// assert!(address.name() == &user_id);
+    /// assert!(address.device_id() == device_id.into());
+    ///```
     pub fn new(name: String, device_id: DeviceId) -> Self {
         ProtocolAddress { name, device_id }
     }

rust/protocol/src/lib.rs

@@ -19,6 +19,11 @@
 #![warn(clippy::unwrap_used)]
 #![deny(unsafe_code)]
 
+// TODO(https://github.com/signalapp/libsignal-client/issues/285): it should be an aspiration to
+// eventually warn and then error for public members without docstrings. Also see
+// https://doc.rust-lang.org/rustdoc/what-to-include.html for background.
+// #![warn(missing_docs)]
+
 mod address;
 mod consts;
 mod crypto;
@@ -42,7 +47,7 @@ mod utils;
 use error::Result;
 
 pub use {
-    address::ProtocolAddress,
+    address::{DeviceId, ProtocolAddress},
     curve::{KeyPair, PrivateKey, PublicKey},
     error::SignalProtocolError,
     fingerprint::{DisplayableFingerprint, Fingerprint, ScannableFingerprint},