Add docs for a few modules, nondestructively!

- Add module docs for the `libsignal_protocol` crate!
- Add docs to the `device-transfer` crate!
- Add docs to `address`!

rust/device-transfer/src/lib.rs

@@ -3,6 +3,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 
+//! Support logic for Signal's device-to-device transfer feature.
+
 #![deny(unsafe_code)]
 
 use chrono::{Datelike, Duration, Utc};
@@ -12,6 +14,7 @@ use picky::x509::{certificate::CertificateBuilder, date::UTCDate};
 use picky::{hash::HashAlgorithm, signature::SignatureAlgorithm};
 use std::fmt;
 
+/// Error types for device transfer.
 #[derive(Copy, Clone, Debug)]
 pub enum Error {
     KeyDecodingFailed,
@@ -27,6 +30,7 @@ impl fmt::Display for Error {
     }
 }
 
+/// Generate a private key of size `bits` and export to PKCS8 format.
 pub fn create_rsa_private_key(bits: usize) -> Result<Vec<u8>, Error> {
     let key = PrivateKey::generate_rsa(bits)
         .map_err(|_| Error::InternalError("RSA key generation failed"))?;
@@ -35,6 +39,9 @@ pub fn create_rsa_private_key(bits: usize) -> Result<Vec<u8>, Error> {
         .map_err(|_| Error::InternalError("Exporting to PKCS8 failed"))?)
 }
 
+/// Generate a self-signed certificate of name `name`, expiring in `days_to_expire`.
+///
+/// `rsa_key_pkcs8` should be the output of [create_rsa_private_key].
 pub fn create_self_signed_cert(
     rsa_key_pkcs8: &[u8],
     name: &str,

rust/protocol/src/address.rs

@@ -1,26 +1,40 @@
 //
-// Copyright 2020 Signal Messenger, LLC.
+// Copyright 2020-2021 Signal Messenger, LLC.
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 
+//! Where to send a message to.
+
 use std::fmt;
 
+/// The type in memory for a *device*, which is separate from an *identity*.
+///
+/// Used in [ProtocolAddress].
+pub type DeviceId = u32;
+
+/// The target of a [crate::SignalMessage].
 #[derive(Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
 pub struct ProtocolAddress {
     name: String,
-    device_id: u32,
+    device_id: DeviceId,
 }
 
 impl ProtocolAddress {
-    pub fn new(name: String, device_id: u32) -> Self {
+    /// Create a new instance.
+    pub fn new(name: String, device_id: DeviceId) -> Self {
         ProtocolAddress { name, device_id }
     }
 
+    /// A unique identifier for the target user.
+    #[inline]
     pub fn name(&self) -> &str {
         &self.name
     }
 
-    pub fn device_id(&self) -> u32 {
+    /// An identifier for the individual device to send to, as Signal does not send messages to all
+    /// devices at a time.
+    #[inline]
+    pub fn device_id(&self) -> DeviceId {
         self.device_id
     }
 }

rust/protocol/src/lib.rs

@@ -3,10 +3,23 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 
+//! Rust implementation of the **[Signal Protocol]** for asynchronous
+//! forward-secret public-key cryptography.
+//!
+//! In particular, this library implements operations conforming to the following specifications:
+//! - the **[X3DH]** key agreement protocol,
+//! - the **[Double Ratchet]** *(Axolotl)* messaging protocol,
+//! - the **[Sesame]** session agreement protocol.
+//!
+//! [Signal Protocol]: https://signal.org/
+//! [X3DH]: https://signal.org/docs/specifications/x3dh/
+//! [Double Ratchet]: https://signal.org/docs/specifications/doubleratchet/
+//! [Sesame]: https://signal.org/docs/specifications/sesame/
+
 #![warn(clippy::unwrap_used)]
 #![deny(unsafe_code)]
 
-mod address;
+pub mod address;
 mod consts;
 mod crypto;
 mod curve;