From eb8ad2d883548d2176eb3fb3cf3023dc819c4923 Mon Sep 17 00:00:00 2001
From: Danny McClanahan <1305167+cosmicexplorer@users.noreply.github.com>
Date: Tue, 4 May 2021 14:17:31 -0700
Subject: [PATCH] add missing docs warning

fix uuid deps

add doctest for `ProtocolAddress::new()`!
---
 Cargo.lock                   |  3 +++
 rust/protocol/Cargo.toml     | 11 +++++++++--
 rust/protocol/src/address.rs | 20 ++++++++++++++++++++
 rust/protocol/src/lib.rs     |  7 ++++++-
 4 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1ee4b42ccb..f1d4ef504f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1953,6 +1953,9 @@ name = "uuid"
 version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bc5cf98d8186244414c848017f0e2676b3fcb46807f6668a97dfe67359a3c4b7"
+dependencies = [
+ "getrandom 0.2.2",
+]
 
 [[package]]
 name = "vcpkg"
diff --git a/rust/protocol/Cargo.toml b/rust/protocol/Cargo.toml
index 59dc5c72e7..959fdbbbdd 100644
--- a/rust/protocol/Cargo.toml
+++ b/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"
 
diff --git a/rust/protocol/src/address.rs b/rust/protocol/src/address.rs
index 4ba09b41bf..d19d8152d2 100644
--- a/rust/protocol/src/address.rs
+++ b/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 }
     }
diff --git a/rust/protocol/src/lib.rs b/rust/protocol/src/lib.rs
index 50d9d4e695..79ae03aee3 100644
--- a/rust/protocol/src/lib.rs
+++ b/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},