deny missing docs in linera-base (#1471)

linera-base/src/crypto.rs

@@ -2,6 +2,8 @@
 // Copyright (c) Zefchain Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Define the cryptographic primitives used by the Linera protocol.
+
 use ed25519_dalek::{self as dalek, Signer, Verifier};
 use generic_array::typenum::Unsigned;
 use serde::{Deserialize, Serialize};
@@ -39,8 +41,9 @@ pub struct CryptoHash(HasherOutput);
 #[derive(Eq, PartialEq, Copy, Clone)]
 pub struct Signature(pub dalek::Signature);
 
-#[derive(Error, Debug)]
 /// Error type for cryptographic errors.
+#[derive(Error, Debug)]
+#[allow(missing_docs)]
 pub enum CryptoError {
     #[error("Signature for object {type_name} is not valid: {error}")]
     InvalidSignature { error: String, type_name: String },
@@ -61,6 +64,7 @@ pub enum CryptoError {
 }
 
 impl PublicKey {
+    /// A fake public key used for testing.
     #[cfg(any(test, feature = "test"))]
     pub fn debug(name: u8) -> PublicKey {
         let addr = [name; dalek::PUBLIC_KEY_LENGTH];
@@ -356,11 +360,13 @@ impl std::fmt::Debug for CryptoHash {
 
 /// Something that we know how to hash.
 pub trait Hashable<Hasher> {
+    /// Send the content of `Self` to the given hasher.
     fn write(&self, hasher: &mut Hasher);
 }
 
 /// Something that we know how to hash and sign.
 pub trait HasTypeName {
+    /// The name of the type.
     fn type_name() -> &'static str;
 }
 
@@ -408,6 +414,7 @@ where
 }
 
 impl CryptoHash {
+    /// Computes a hash.
     pub fn new<T: ?Sized>(value: &T) -> Self
     where
         T: BcsHashable,
@@ -419,12 +426,14 @@ impl CryptoHash {
         CryptoHash(hasher.finalize())
     }
 
+    /// Reads the bytes of the hash value.
     pub fn as_bytes(&self) -> &HasherOutput {
         &self.0
     }
 }
 
 impl Signature {
+    /// Computes a signature.
     pub fn new<T>(value: &T, secret: &KeyPair) -> Self
     where
         T: BcsSignable,
@@ -445,6 +454,7 @@ impl Signature {
         public_key.verify(&message, &self.0)
     }
 
+    /// Checks a signature.
     pub fn check<T>(&self, value: &T, author: PublicKey) -> Result<(), CryptoError>
     where
         T: BcsSignable + std::fmt::Debug,
@@ -474,6 +484,7 @@ impl Signature {
         dalek::verify_batch(&messages[..], &signatures[..], &public_keys[..])
     }
 
+    /// Verifies a batch of signatures.
     pub fn verify_batch<'a, T, I>(value: &'a T, votes: I) -> Result<(), CryptoError>
     where
         T: BcsSignable,

linera-base/src/data_types.rs

@@ -2,6 +2,8 @@
 // Copyright (c) Zefchain Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Core data-types used in the Linera protocol.
+
 use serde::{Deserialize, Serialize};
 use std::{
     fmt,
@@ -59,9 +61,12 @@ pub struct BlockHeight(pub u64);
     Eq, PartialEq, Ord, PartialOrd, Copy, Clone, Hash, Default, Debug, Serialize, Deserialize,
 )]
 pub enum Round {
+    /// The initial fast round.
     #[default]
     Fast,
+    /// The N-th multi-leader round.
     MultiLeader(u32),
+    /// The N-th single-leader round.
     SingleLeader(u32),
 }
 
@@ -139,8 +144,9 @@ impl fmt::Display for Timestamp {
     }
 }
 
-#[derive(Debug, Error)]
 /// An error type for arithmetic errors.
+#[derive(Debug, Error)]
+#[allow(missing_docs)]
 pub enum ArithmeticError {
     #[error("Number overflow")]
     Overflow,
@@ -151,9 +157,13 @@ pub enum ArithmeticError {
 macro_rules! impl_wrapped_number {
     ($name:ident, $wrapped:ident) => {
         impl $name {
+            /// The zero value.
             pub const ZERO: Self = Self(0);
+
+            /// The maximum value.
             pub const MAX: Self = Self($wrapped::MAX);
 
+            /// Checked addition.
             pub fn try_add(self, other: Self) -> Result<Self, ArithmeticError> {
                 let val = self
                     .0
@@ -162,16 +172,19 @@ macro_rules! impl_wrapped_number {
                 Ok(Self(val))
             }
 
+            /// Checked increment.
             pub fn try_add_one(self) -> Result<Self, ArithmeticError> {
                 let val = self.0.checked_add(1).ok_or(ArithmeticError::Overflow)?;
                 Ok(Self(val))
             }
 
+            /// Saturating addition.
             pub fn saturating_add(self, other: Self) -> Self {
                 let val = self.0.saturating_add(other.0);
                 Self(val)
             }
 
+            /// Checked subtraction.
             pub fn try_sub(self, other: Self) -> Result<Self, ArithmeticError> {
                 let val = self
                     .0
@@ -180,16 +193,19 @@ macro_rules! impl_wrapped_number {
                 Ok(Self(val))
             }
 
+            /// Checked decrement.
             pub fn try_sub_one(self) -> Result<Self, ArithmeticError> {
                 let val = self.0.checked_sub(1).ok_or(ArithmeticError::Underflow)?;
                 Ok(Self(val))
             }
 
+            /// Saturating subtraction.
             pub fn saturating_sub(self, other: Self) -> Self {
                 let val = self.0.saturating_sub(other.0);
                 Self(val)
             }
 
+            /// Checked in-place addition.
             pub fn try_add_assign(&mut self, other: Self) -> Result<(), ArithmeticError> {
                 self.0 = self
                     .0
@@ -198,15 +214,18 @@ macro_rules! impl_wrapped_number {
                 Ok(())
             }
 
+            /// Checked in-place increment.
             pub fn try_add_assign_one(&mut self) -> Result<(), ArithmeticError> {
                 self.0 = self.0.checked_add(1).ok_or(ArithmeticError::Overflow)?;
                 Ok(())
             }
 
+            /// Saturating in-place addition.
             pub fn saturating_add_assign(&mut self, other: Self) {
                 self.0 = self.0.saturating_add(other.0);
             }
 
+            /// Checked in-place subtraction.
             pub fn try_sub_assign(&mut self, other: Self) -> Result<(), ArithmeticError> {
                 self.0 = self
                     .0
@@ -215,15 +234,18 @@ macro_rules! impl_wrapped_number {
                 Ok(())
             }
 
+            /// Saturating multiplication.
             pub fn saturating_mul(&self, other: $wrapped) -> Self {
                 Self(self.0.saturating_mul(other))
             }
 
+            /// Checked multiplication.
             pub fn try_mul(self, other: $wrapped) -> Result<Self, ArithmeticError> {
                 let val = self.0.checked_mul(other).ok_or(ArithmeticError::Overflow)?;
                 Ok(Self(val))
             }
 
+            /// Checked in-place multiplication.
             pub fn try_mul_assign(&mut self, other: $wrapped) -> Result<(), ArithmeticError> {
                 self.0 = self.0.checked_mul(other).ok_or(ArithmeticError::Overflow)?;
                 Ok(())
@@ -299,6 +321,7 @@ impl fmt::Display for Amount {
 }
 
 #[derive(Error, Debug)]
+#[allow(missing_docs)]
 pub enum ParseAmountError {
     #[error("cannot parse amount")]
     Parse,
@@ -367,21 +390,25 @@ impl fmt::Display for Round {
 }
 
 impl Round {
+    /// Whether the round is a multi-leader round.
     pub fn is_multi_leader(&self) -> bool {
         matches!(self, Round::MultiLeader(_))
     }
 
+    /// Whether the round is the fast round.
     pub fn is_fast(&self) -> bool {
         matches!(self, Round::Fast)
     }
 
+    /// The index of a round amongst the rounds of the same category.
     pub fn number(&self) -> u32 {
         match self {
             Round::Fast => 0,
             Round::MultiLeader(r) | Round::SingleLeader(r) => *r,
         }
     }
 
+    /// The category of the round as a string.
     pub fn type_name(&self) -> &'static str {
         match self {
             Round::Fast => "fast",
@@ -398,7 +425,10 @@ impl<'a> std::iter::Sum<&'a Amount> for Amount {
 }
 
 impl Amount {
+    /// The base-10 exponent representing how much a token can be divided.
     pub const DECIMAL_PLACES: u8 = 18;
+
+    /// One token.
     pub const ONE: Amount = Amount(10u128.pow(Amount::DECIMAL_PLACES as u32));
 
     /// Returns an `Amount` corresponding to that many tokens, or `Amount::MAX` if saturated.

linera-base/src/graphql.rs

@@ -18,6 +18,7 @@ macro_rules! doc_scalar {
 
 /// An error trying to parse the hex-digits of a BCS-encoded value.
 #[derive(thiserror::Error, Debug)]
+#[allow(missing_docs)]
 pub enum BcsHexParseError {
     #[error("Invalid BCS: {0}")]
     Bcs(#[from] bcs::Error),

linera-base/src/identifiers.rs

@@ -1,6 +1,8 @@
 // Copyright (c) Zefchain Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Core identifiers used by the Linera protocol.
+
 use crate::{
     bcs_scalar,
     crypto::{BcsHashable, CryptoError, CryptoHash, PublicKey},
@@ -30,6 +32,7 @@ pub enum ChainDescription {
 }
 
 impl ChainDescription {
+    /// Whether the chain was created by another chain.
     pub fn is_child(&self) -> bool {
         matches!(self, ChainDescription::Child(_))
     }
@@ -45,8 +48,11 @@ pub struct ChainId(pub CryptoHash);
 #[derive(Eq, PartialEq, Ord, PartialOrd, Copy, Clone, Hash, Debug, Serialize, Deserialize)]
 #[cfg_attr(any(test, feature = "test"), derive(Default))]
 pub struct MessageId {
+    /// The chain ID that created the message.
     pub chain_id: ChainId,
+    /// The height of the block that created the message.
     pub height: BlockHeight,
+    /// The index of the message inside the block.
     pub index: u32,
 }
 
@@ -62,6 +68,7 @@ pub struct ApplicationId<A = ()> {
 /// A unique identifier for an application bytecode.
 #[cfg_attr(any(test, feature = "test"), derive(Default))]
 pub struct BytecodeId<A = ()> {
+    /// The message ID that published the bytecode.
     pub message_id: MessageId,
     _phantom: std::marker::PhantomData<A>,
 }
@@ -89,6 +96,7 @@ pub enum Destination {
 }
 
 impl Destination {
+    /// Whether the destination is a broadcast channel.
     pub fn is_channel(&self) -> bool {
         matches!(self, Destination::Subscribers(_))
     }
@@ -113,6 +121,7 @@ impl From<Vec<u8>> for ChannelName {
 }
 
 impl ChannelName {
+    /// Turns the channel into bytes.
     pub fn into_bytes(self) -> Vec<u8> {
         self.0
     }
@@ -231,13 +240,15 @@ impl<'de, A> Deserialize<'de> for BytecodeId<A> {
 }
 
 impl BytecodeId {
+    /// Creates a bytecode ID from a message ID.
     pub fn new(message_id: MessageId) -> Self {
         BytecodeId {
             message_id,
             _phantom: std::marker::PhantomData,
         }
     }
 
+    /// Specializes a bytecode ID for a given ABI.
     pub fn with_abi<A>(self) -> BytecodeId<A> {
         BytecodeId {
             message_id: self.message_id,
@@ -247,6 +258,7 @@ impl BytecodeId {
 }
 
 impl<A> BytecodeId<A> {
+    /// Forgets the ABI of a bytecode ID (if any).
     pub fn forget_abi(self) -> BytecodeId {
         BytecodeId {
             message_id: self.message_id,
@@ -382,6 +394,7 @@ impl<'de, A> Deserialize<'de> for ApplicationId<A> {
 }
 
 impl ApplicationId {
+    /// Specializes an application ID for a given ABI.
     pub fn with_abi<A>(self) -> ApplicationId<A> {
         ApplicationId {
             bytecode_id: self.bytecode_id.with_abi(),
@@ -391,6 +404,7 @@ impl ApplicationId {
 }
 
 impl<A> ApplicationId<A> {
+    /// Forgets the ABI of a bytecode ID (if any).
     pub fn forget_abi(self) -> ApplicationId {
         ApplicationId {
             bytecode_id: self.bytecode_id.forget_abi(),
@@ -460,6 +474,7 @@ impl<A> Debug for SessionId<A> {
 }
 
 impl SessionId {
+    /// Specializes a session ID for a given ABI.
     pub fn with_abi<A>(self) -> SessionId<A> {
         SessionId {
             application_id: self.application_id.with_abi(),
@@ -469,6 +484,7 @@ impl SessionId {
 }
 
 impl<A> SessionId<A> {
+    /// Forgets the ABI of a session ID (if any).
     pub fn forget_abi(self) -> SessionId {
         SessionId {
             application_id: self.application_id.forget_abi(),
@@ -593,10 +609,12 @@ impl From<ChainDescription> for ChainId {
 }
 
 impl ChainId {
+    /// The chain ID representing the N-th chain created at genesis time.
     pub fn root(index: u32) -> Self {
         Self(CryptoHash::new(&ChainDescription::Root(index)))
     }
 
+    /// The chain ID representing the chain created by the given message.
     pub fn child(id: MessageId) -> Self {
         Self(CryptoHash::new(&ChainDescription::Child(id)))
     }

linera-base/src/lib.rs

@@ -1,6 +1,8 @@
 // Copyright (c) Zefchain Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+#![deny(missing_docs)]
+
 //! This module provides a common set of types and library functions that are shared
 //! between the Linera protocol (compiled from Rust to native code) and Linera
 //! applications (compiled from Rust to Wasm).