chore: improve some code documentation

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

@@ -7,11 +7,11 @@ use super::ServiceAddr;
 /// The AS-local host identifier of a SCION address.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum HostAddr {
-    /// An IPv4 host address
+    /// An IPv4 host address.
     V4(Ipv4Addr),
-    /// An IPv6 host address
+    /// An IPv6 host address.
     V6(Ipv6Addr),
-    /// A SCION-service host address
+    /// A SCION-service host address.
     Svc(ServiceAddr),
 }
 

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

@@ -32,7 +32,7 @@ impl IsdAsn {
         Asn::new(self.0 & 0xffff_ffff_ffff)
     }
 
-    /// Return true if either the ISD or AS numbers are wildcards
+    /// Returns true if either the ISD or AS numbers are wildcards.
     ///
     /// # Examples
     ///

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

@@ -5,10 +5,11 @@ use std::{
 
 use super::{error::AddressKind, AddressParseError};
 
-/// Identifier of a SCION Isolation Domain
+/// Identifier of a SCION Isolation Domain.
 ///
-/// See formatting and allocations here:
-/// <https://github.com/scionproto/scion/wiki/ISD-and-AS-numbering#isd-numbers>
+/// See formatting and allocations [here][isd-and-as-numbering].
+///
+/// [isd-and-as-numbering]: https://github.com/scionproto/scion/wiki/ISD-and-AS-numbering#isd-numbers
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 #[repr(transparent)]
 pub struct Isd(u16);
@@ -29,7 +30,7 @@ impl Isd {
         self.0
     }
 
-    /// Return true for the special 'wildcard' AS number
+    /// Return true for the special 'wildcard' AS number.
     ///
     /// # Examples
     ///

crates/scion-proto/src/datagram.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//! Representation, encoding, and decoding of UDP datagrams.
 
 use bytes::{Buf, BufMut, Bytes, BytesMut};
 
@@ -23,7 +23,7 @@ pub enum UdpEncodeError {
     PayloadTooLarge,
 }
 
-/// Scion UDP datagram
+/// SCION UDP datagram.
 ///
 /// The SCION UDP datagram format includes a checksum that is calculated based on
 /// the [RFC].
@@ -42,7 +42,13 @@ pub struct UdpDatagram {
 }
 
 impl UdpDatagram {
+    /// SCION protocol number for UDP.
+    ///
+    /// See the [IETF SCION-dataplane RFC draft][rfc] for possible values.
+    ///
+    ///[rfc]: https://www.ietf.org/archive/id/draft-dekater-scion-dataplane-00.html#protnum
     pub const PROTOCOL_NUMBER: u8 = 17;
+    /// Length in bytes of the UDP header.
     pub const HEADER_LEN: usize = 8;
 
     /// Creates a new datagram setting the length field appropriately
@@ -105,10 +111,7 @@ impl WireEncodeVec<2> for UdpDatagram {
     }
 }
 
-impl<T> WireDecode<T> for UdpDatagram
-where
-    T: Buf,
-{
+impl<T: Buf> WireDecode<T> for UdpDatagram {
     type Error = UdpDecodeError;
 
     fn decode(data: &mut T) -> Result<Self, Self::Error> {

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

@@ -135,13 +135,10 @@ impl WireEncode for MaybeEncoded<HostAddr, (AddressInfo, RawHostAddress)> {
     }
 }
 
-fn maybe_decode_host<T>(
+fn maybe_decode_host<T: Buf>(
     data: &mut T,
     info: AddressInfo,
-) -> Result<MaybeEncoded<HostAddr, (AddressInfo, RawHostAddress)>, DecodeError>
-where
-    T: Buf,
-{
+) -> Result<MaybeEncoded<HostAddr, (AddressInfo, RawHostAddress)>, DecodeError> {
     if data.remaining() < info.address_length() {
         return Err(DecodeError::PacketEmptyOrTruncated);
     }

crates/scion-proto/src/path.rs

@@ -26,16 +26,16 @@ pub use metadata::{GeoCoordinates, LinkType, PathInterface, PathMetadata};
 pub mod epic;
 pub use epic::EpicAuths;
 
-/// A SCION end-to-end path with optional metadata
+/// A SCION end-to-end path with optional metadata.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Path {
-    /// The raw bytes to be added as the path header to SCION dataplane packets
+    /// The raw bytes to be added as the path header to SCION dataplane packets.
     pub dataplane_path: DataplanePath,
-    /// The underlay address (IP + port) of the next hop; i.e., the local border router
+    /// The underlay address (IP + port) of the next hop; i.e., the local border router.
     pub underlay_next_hop: Option<SocketAddr>,
-    /// The ISD-ASN where the path starts and ends
+    /// The ISD-ASN where the path starts and ends.
     pub isd_asn: ByEndpoint<IsdAsn>,
-    /// Path metadata
+    /// Path metadata.
     pub metadata: Option<PathMetadata>,
 }
 

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

@@ -8,7 +8,7 @@ use crate::{
     wire_encoding::{WireDecode, WireDecodeWithContext, WireEncode},
 };
 
-/// SCION path types that may be encountered in a packet
+/// SCION path types that may be encountered in a packet.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
@@ -23,7 +23,7 @@ pub enum PathType {
     Epic,
     /// Experimental Colibri path type.
     Colibri,
-    /// Other, unrecognized path types
+    /// Other, unrecognized path types.
     Other(u8),
 }
 
@@ -58,24 +58,24 @@ impl From<u8> for PathType {
 #[error("unsupported path type {0}")]
 pub struct UnsupportedPathType(pub u8);
 
-/// Dataplane path found in a SCION packet
+/// Dataplane path found in a SCION packet.
 #[derive(Debug, Clone, PartialEq)]
 pub enum DataplanePath {
-    /// The empty path type, used for intra-AS hops
+    /// The empty path type, used for intra-AS hops.
     EmptyPath,
     /// The standard SCION path header.
     Standard(StandardPath),
     /// The raw bytes of an unsupported path header type.
     Unsupported {
-        /// The path's type
+        /// The path's type.
         path_type: PathType,
-        /// The raw encoded path
+        /// The raw encoded path.
         bytes: Bytes,
     },
 }
 
 impl DataplanePath {
-    /// Returns a deep copy of the object
+    /// Returns a deep copy of the object.
     pub fn deep_copy(&self) -> Self {
         match self {
             Self::EmptyPath => Self::EmptyPath,
@@ -87,7 +87,7 @@ impl DataplanePath {
         }
     }
 
-    /// Returns the path's type
+    /// Returns the path's type.
     pub fn path_type(&self) -> PathType {
         match self {
             Self::EmptyPath => PathType::Empty,
@@ -117,7 +117,7 @@ impl DataplanePath {
         Ok(self)
     }
 
-    /// Returns true iff the path is a [`DataplanePath::EmptyPath`]
+    /// Returns true iff the path is a [`DataplanePath::EmptyPath`].
     pub fn is_empty(&self) -> bool {
         self == &Self::EmptyPath
     }

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

@@ -3,12 +3,12 @@
 use bytes::Bytes;
 use scion_grpc::daemon::v1 as daemon_grpc;
 
-/// Authenticators to compute EPIC hop validation fields (HVFs)
+/// Authenticators to compute EPIC hop validation fields (HVFs).
 #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
 pub struct EpicAuths {
-    /// Key to compute the penultimate hop validation field
+    /// Key to compute the penultimate hop validation field.
     pub phvf: Bytes,
-    /// Key to compute the last hop validation field
+    /// Key to compute the last hop validation field.
     pub lhvf: Bytes,
 }
 

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

@@ -1,8 +1,9 @@
-#![allow(missing_docs)]
+//! Errors encountered when parsing SCION paths.
 
 use std::fmt::Display;
 
 #[non_exhaustive]
+#[allow(missing_docs)]
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 /// Error kinds for dataplane paths.
 pub enum DataplanePathErrorKind {
@@ -32,6 +33,7 @@ impl Display for DataplanePathErrorKind {
 #[derive(Eq, PartialEq, Clone, Debug, thiserror::Error)]
 pub struct PathParseError(PathParseErrorKind);
 
+#[allow(missing_docs)]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PathParseErrorKind {
     EmptyRaw,

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

@@ -16,7 +16,7 @@ pub use geo::GeoCoordinates;
 pub mod path_interface;
 pub use path_interface::PathInterface;
 
-/// Metadata of SCION end-to-end paths
+/// Metadata of SCION end-to-end paths.
 ///
 /// Fields are set to `None` if unset or trying to convert an invalid value.
 /// For vectors, individual entries are `None` if trying to convert an invalid value.

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

@@ -2,7 +2,7 @@
 
 use scion_grpc::daemon::v1 as daemon_grpc;
 
-/// Geographic coordinates with latitude and longitude
+/// Geographic coordinates with latitude and longitude.
 // Using a custom type to prevent importing a library here
 #[derive(PartialEq, Clone, Debug, Default)]
 pub struct GeoCoordinates {

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

@@ -1,9 +1,9 @@
 /// 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 link type.
     Invalid = -1,
-    /// Unspecified
+    /// Unspecified.
     #[default]
     Unset = 0,
     /// Direct physical connection.

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

@@ -5,7 +5,7 @@ use crate::{
     path::{PathParseError, PathParseErrorKind},
 };
 
-/// SCION interface with the AS's ISD-ASN and the interface's ID
+/// 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

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

@@ -1,4 +1,4 @@
-//! A standard SCION path,
+//! A standard SCION path.
 
 use std::mem;
 
@@ -11,13 +11,13 @@ use crate::{
 };
 
 wire_encoding::bounded_uint! {
-    /// A 2-bit index into the info fields
+    /// A 2-bit index into the info fields.
     #[derive(Default)]
     pub struct InfoFieldIndex(u8 : 2);
 }
 
 wire_encoding::bounded_uint! {
-    /// A 6-bit index into the hop fields
+    /// A 6-bit index into the hop fields.
     #[derive(Default)]
     pub struct HopFieldIndex(u8 : 6);
 }
@@ -70,9 +70,9 @@ pub struct PathMetaHeader {
 impl PathMetaHeader {
     /// The length of a path meta header in bytes.
     pub const LENGTH: usize = 4;
-    /// The length of an info field in bytes
+    /// The length of an info field in bytes.
     pub const INFO_FIELD_LENGTH: usize = 8;
-    /// The length of a hop field in bytes
+    /// The length of a hop field in bytes.
     pub const HOP_FIELD_LENGTH: usize = 12;
 
     /// The number of info fields.
@@ -238,15 +238,15 @@ impl StandardPath {
         &self.meta_header
     }
 
-    /// Creates a deep copy of this path
+    /// Creates a deep copy of this path.
     pub fn deep_copy(&self) -> Self {
         Self {
             meta_header: self.meta_header.clone(),
             encoded_path: Bytes::copy_from_slice(&self.encoded_path),
         }
     }
 
-    /// Returns the encoded raw path
+    /// Returns the encoded raw path.
     pub fn raw(&self) -> Bytes {
         self.encoded_path.clone()
     }

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

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//! Common header for the reliable relay protocol.
 
 use std::net::{IpAddr, SocketAddr};
 
@@ -23,10 +23,12 @@ pub enum DecodeError {
     InvalidAddressType(u8),
 }
 
-/// Partial or fully decoded commonHeader
+/// Partial or fully decoded [`CommonHeader`].
 #[derive(Debug)]
 pub enum DecodedHeader {
+    /// A partially decoded common header.
     Partial(PartialHeader),
+    /// A fully decoded common header.
     Full(CommonHeader),
 }
 
@@ -40,10 +42,12 @@ impl DecodedHeader {
     }
 }
 
-/// A partially decoded common header
+/// A partially decoded common header.
 #[derive(Copy, Clone, Debug)]
 pub struct PartialHeader {
+    /// The host type of the destination (when sending) or the last hop (when receiving).
     pub host_type: HostType,
+    /// The length of the payload.
     pub payload_length: u32,
 }
 
@@ -117,7 +121,7 @@ impl PartialHeader {
 #[derive(Default, Debug, Copy, Clone)]
 pub struct CommonHeader {
     /// The destination to which to relay the packet (when sent), or the last hop
-    /// when receiving.
+    /// (when receiving).
     pub destination: Option<SocketAddr>,
     /// The length of the associated payload.
     pub payload_length: u32,