docs: generally disallow missing Rust docs

Add missing docs in some places and  in others.

Cargo.toml

@@ -19,4 +19,4 @@ tonic-build = "0.10"
 tracing = "0.1.40"
 
 [workspace.lints.rust]
-missing_docs = "allow"
+missing_docs = "deny"

crates/scion-grpc/Cargo.toml

@@ -16,5 +16,5 @@ tonic-build = { workspace = true }
 [lib]
 bench = false
 
-[lints]
-workspace = true
+[lints.rust]
+missing_docs = "allow"

crates/scion-grpc/src/lib.rs

@@ -1,5 +1,5 @@
-//! `scion-grpc` provides bindings [gRPC](https://grpc.io/) types and services used within SCION's
-//! control plane.
+//! Bindings for [gRPC](https://grpc.io/) types and services used within SCION's control plane.
+
 pub use prost::Message;
 
 pub mod drkey {

crates/scion-proto/benches/checksum.rs

@@ -1,3 +1,7 @@
+#![allow(missing_docs)]
+
+//! Comparison between different checksum implementations.
+
 use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
 use rand::{Fill, SeedableRng};
 use rand_xorshift::XorShiftRng;

crates/scion-proto/src/address.rs

@@ -1,3 +1,5 @@
+//! SCION addresses at various granularities (ASes, endhosts, sockets).
+
 mod asn;
 pub use asn::Asn;
 

crates/scion-proto/src/address/host.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
 
 use super::ServiceAddr;

crates/scion-proto/src/address/scion_address.rs

@@ -1,3 +1,5 @@
+//! SCION endhost addresses.
+
 use std::net::{Ipv4Addr, Ipv6Addr};
 
 use super::{error::AddressKind, AddressParseError, HostAddr, IsdAsn, ServiceAddr};
@@ -17,6 +19,8 @@ pub enum ScionAddr {
 }
 
 impl ScionAddr {
+    /// Creates a new SCION address based on the [`IsdAsn`] of the AS and the endhost's
+    /// [`HostAddr`].
     pub const fn new(isd_asn: IsdAsn, host: HostAddr) -> Self {
         match host {
             HostAddr::V4(host) => Self::V4(ScionAddrV4::new(isd_asn, host)),

crates/scion-proto/src/datagram.rs

@@ -1,10 +1,13 @@
+#![allow(missing_docs)]
+
 use bytes::{Buf, BufMut, Bytes, BytesMut};
 
 use crate::{
     packet::{AddressHeader, ByEndpoint, ChecksumDigest, InadequateBufferSize},
     wire_encoding::{WireDecode, WireEncodeVec},
 };
 
+#[allow(missing_docs)]
 #[derive(Debug, thiserror::Error)]
 pub enum UdpDecodeError {
     #[error("datagram is empty or was truncated")]
@@ -13,6 +16,7 @@ pub enum UdpDecodeError {
     WrongProtocolNumber(u8),
 }
 
+#[allow(missing_docs)]
 #[derive(Debug, thiserror::Error)]
 pub enum UdpEncodeError {
     #[error("payload length cannot be encoded")]

crates/scion-proto/src/lib.rs

@@ -1,3 +1,5 @@
+//! Types, conversion functions, parsing, and encoding for the SCION endhost stack.
+
 pub mod address;
 pub mod datagram;
 pub mod packet;

crates/scion-proto/src/packet/error.rs

@@ -1,8 +1,11 @@
+//! Errors raised when encoding or decoding SCION packets.
+
 use super::Version;
 use crate::path::DataplanePathErrorKind;
 
 /// Errors raised when failing to decode a [`super::ScionPacketRaw`] or [`super::ScionPacketUdp`]
 /// or its constituents.
+#[allow(missing_docs)]
 #[derive(Debug, thiserror::Error, PartialEq, Eq, Clone, Copy)]
 pub enum DecodeError {
     #[error("cannot decode packet with unsupported header version {0:?}")]
@@ -26,6 +29,7 @@ impl From<DataplanePathErrorKind> for DecodeError {
 }
 
 /// Errors raised when failing to encode a [`super::ScionPacketRaw`] or [`super::ScionPacketUdp`].
+#[allow(missing_docs)]
 #[derive(Debug, thiserror::Error, PartialEq, Eq, Clone, Copy)]
 pub enum EncodeError {
     #[error("packet payload is too large")]

crates/scion-proto/src/packet/headers.rs

@@ -1,3 +1,5 @@
+//! SCION packet headers.
+
 mod common_header;
 use std::num::NonZeroU8;
 
@@ -13,7 +15,7 @@ pub use path_header::DataplanePath;
 use super::{EncodeError, InadequateBufferSize};
 use crate::{address::SocketAddr, path::Path, wire_encoding::WireEncode};
 
-/// SCION packet headers
+/// SCION packet headers.
 #[derive(Debug, Clone)]
 pub struct ScionHeaders {
     /// Metadata about the remaining headers and payload.
@@ -25,6 +27,8 @@ pub struct ScionHeaders {
 }
 
 impl ScionHeaders {
+    /// Creates a new [`ScionHeaders`] object given the source and destination [`SocketAddr`],
+    /// the [`Path`], the next-header value, and the payload length
     pub fn new(
         endhosts: &ByEndpoint<SocketAddr>,
         path: &Path,
@@ -90,8 +94,10 @@ impl WireEncode for ScionHeaders {
 /// Instances of an object associated with both a source and destination endpoint.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Default)]
 pub struct ByEndpoint<T> {
-    pub destination: T,
+    /// The value for the source
     pub source: T,
+    /// The value for the destination
+    pub destination: T,
 }
 
 impl<T: Clone> ByEndpoint<T> {
@@ -105,6 +111,7 @@ impl<T: Clone> ByEndpoint<T> {
 }
 
 impl<T> ByEndpoint<T> {
+    /// Applies the `function` to both source and destination
     pub fn map<U, F>(&self, function: F) -> ByEndpoint<U>
     where
         F: Fn(&T) -> U,
@@ -117,6 +124,7 @@ impl<T> ByEndpoint<T> {
 }
 
 impl<T: PartialEq> ByEndpoint<T> {
+    /// Returns true iff the source and destination values are equal
     pub fn are_equal(&self) -> bool {
         self.source == self.destination
     }

crates/scion-proto/src/packet/headers/common_header.rs

@@ -170,7 +170,7 @@ impl AddressInfo {
     /// Gets the host type.
     ///
     /// The host type is a combination of the stored type and length. It is returned as
-    /// an enum of type [`HostType`] if it is recognised, otherwise the undecoded 4-bit
+    /// an enum of type [`HostType`] if it is recognized, otherwise the undecoded 4-bit
     /// value is returned as a u8.
     pub fn host_type(&self) -> MaybeEncoded<HostType, u8> {
         match self.0 {

crates/scion-proto/src/packet/headers/path_header.rs

@@ -15,13 +15,13 @@ pub enum PathType {
     Empty,
     /// The standard SCION path type.
     Scion,
-    /// One-hop paths between neighbouring border routers.
+    /// One-hop paths between neighboring border routers.
     OneHop,
     /// Experimental Epic path type.
     Epic,
     /// Experimental Colibri path type.
     Colibri,
-    /// Other, unrecognised path types
+    /// Other, unrecognized path types
     Other(u8),
 }
 
@@ -63,10 +63,16 @@ pub enum DataplanePath {
     /// The standard SCION path header.
     Standard(StandardPath),
     /// The raw bytes of an unsupported path header type.
-    Unsupported { path_type: PathType, bytes: Bytes },
+    Unsupported {
+        /// The path's type
+        path_type: PathType,
+        /// The raw encoded path
+        bytes: Bytes,
+    },
 }
 
 impl DataplanePath {
+    /// Returns a deep copy of the object
     pub fn deep_copy(&self) -> Self {
         match self {
             Self::EmptyPath => Self::EmptyPath,
@@ -78,6 +84,7 @@ impl DataplanePath {
         }
     }
 
+    /// Returns the path's type
     pub fn path_type(&self) -> PathType {
         match self {
             Self::EmptyPath => PathType::Empty,
@@ -86,6 +93,7 @@ impl DataplanePath {
         }
     }
 
+    /// Returns true iff the path is a [`DataplanePath::EmptyPath`]
     pub fn is_empty(&self) -> bool {
         self == &Self::EmptyPath
     }

crates/scion-proto/src/packet/raw.rs

@@ -1,3 +1,5 @@
+//! Raw SCION packets.
+
 use bytes::{Buf, Bytes};
 
 use super::{
@@ -26,6 +28,7 @@ pub struct ScionPacketRaw {
 }
 
 impl ScionPacketRaw {
+    /// Creates a new SCION raw packet
     pub fn new(
         endhosts: &ByEndpoint<SocketAddr>,
         path: &Path,

crates/scion-proto/src/packet/udp.rs

@@ -1,3 +1,5 @@
+//! SCION packets containing UDP datagrams.
+
 use bytes::Bytes;
 
 use super::{InadequateBufferSize, ScionHeaders, ScionPacketRaw};
@@ -18,6 +20,7 @@ pub struct ScionPacketUdp {
 }
 
 impl ScionPacketUdp {
+    /// Creates a new SCION UDP packet based on the UDP payload
     pub fn new(
         endhosts: &ByEndpoint<SocketAddr>,
         path: &Path,

crates/scion-proto/src/path.rs

@@ -1,3 +1,8 @@
+//! SCION path types.
+//!
+//! This module contains types for SCION paths and metadata as well as encoding and decoding
+//! functions.
+
 use std::net::SocketAddr;
 
 use bytes::Bytes;
@@ -36,6 +41,7 @@ pub struct Path {
     pub metadata: Option<PathMetadata>,
 }
 
+#[allow(missing_docs)]
 impl Path {
     pub fn new(
         dataplane_path: DataplanePath,

crates/scion-proto/src/path/epic.rs

@@ -1,3 +1,5 @@
+//! Types required for the EPIC path type.
+
 use bytes::Bytes;
 use scion_grpc::daemon::v1 as daemon_grpc;
 

crates/scion-proto/src/path/error.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::fmt::Display;
 
 #[non_exhaustive]

crates/scion-proto/src/path/metadata/geo.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use scion_grpc::daemon::v1 as daemon_grpc;
 
 /// Geographic coordinates with latitude and longitude

crates/scion-proto/src/path/metadata/linktype.rs

@@ -1,13 +1,16 @@
+/// The type of an inter-domain link based on the underlay connection.
 #[derive(Debug, PartialEq, Eq, Clone, Copy, Hash, Default)]
 pub enum LinkType {
+    /// Invalid link type
     Invalid = -1,
+    /// Unspecified
     #[default]
     Unset = 0,
-    // Direct physical connection.
+    /// Direct physical connection.
     Direct,
-    // Connection with local routing/switching.
+    /// Connection with local routing/switching.
     MultiHop,
-    // Connection overlaid over publicly routed Internet.
+    /// Connection overlaid over publicly routed Internet.
     OpenNet,
 }
 

crates/scion-proto/src/path/metadata/path_interface.rs

@@ -8,7 +8,9 @@ use crate::{
 /// SCION interface with the AS's ISD-ASN and the interface's ID
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct PathInterface {
+    /// The ISD-ASN of the AS where the interface is located
     pub isd_asn: IsdAsn,
+    /// The AS-local interface ID
     pub id: u16,
 }
 

crates/scion-proto/src/path/standard.rs

@@ -1,3 +1,5 @@
+//! A standard SCION path,
+
 use std::mem;
 
 use bytes::{Buf, Bytes};
@@ -195,6 +197,7 @@ impl StandardPath {
         &self.meta_header
     }
 
+    /// Creates a deep copy of this path
     pub fn deep_copy(&self) -> Self {
         Self {
             meta_header: self.meta_header.clone(),

crates/scion-proto/src/reliable.rs

@@ -1,3 +1,5 @@
+//! Protocol including message formats to communicate with the SCION dispatcher.
+
 use std::net::SocketAddr;
 
 use bytes::Bytes;

crates/scion-proto/src/reliable/common_header.rs

@@ -1,13 +1,14 @@
+#![allow(missing_docs)]
+
 use std::net::{IpAddr, SocketAddr};
 
 use bytes::{Buf, BufMut};
-use thiserror::Error;
 
 use super::{wire_utils::encoded_address_and_port_length, ADDRESS_TYPE_OCTETS};
 use crate::{address::HostType, packet::InadequateBufferSize, wire_encoding::WireEncode};
 
 /// Errors occurring during decoding of packets received over the reliable-relay protocol.
-#[derive(Error, Debug, Eq, PartialEq, Clone, Copy)]
+#[derive(thiserror::Error, Debug, Eq, PartialEq, Clone, Copy)]
 pub enum DecodeError {
     /// The decoded packet started with an incorrect token. This indicates a
     /// synchronisation issue with the relay.

crates/scion-proto/src/reliable/parser.rs

@@ -12,6 +12,7 @@ pub struct StreamParser {
 }
 
 impl StreamParser {
+    /// Creates a new empty [`StreamParser`]
     pub fn new() -> Self {
         Self::default()
     }

crates/scion-proto/src/reliable/registration.rs

@@ -168,6 +168,7 @@ fn encode_address(buffer: &mut impl BufMut, address: &SocketAddr) {
 pub struct InvalidRegistrationAddressError;
 
 /// Errors indicating a failure in the registration protocol.
+#[allow(missing_docs)]
 #[derive(Debug, PartialEq, Eq, Clone, Copy, thiserror::Error)]
 pub enum RegistrationError {
     #[error("invalid response length")]

crates/scion-proto/src/wire_encoding.rs

@@ -1,3 +1,5 @@
+//! Traits and tools to decode and encode objects.
+
 use bytes::{Buf, BufMut, Bytes, BytesMut};
 
 use crate::packet::InadequateBufferSize;
@@ -209,6 +211,8 @@ impl<T, U> MaybeEncoded<T, U>
 where
     T: Into<U>,
 {
+    /// Returns the encoded value of a [`MaybeEncoded`] object (encoding the given value if
+    /// necessary).
     pub fn into_encoded(self) -> U {
         match self {
             MaybeEncoded::Decoded(decoded) => decoded.into(),

crates/scion/src/daemon.rs

@@ -1,3 +1,5 @@
+//! Tools to communicate with the local SCION daemon.
+
 mod messages;
 pub use messages::{AsInfo, PathRequest};