Skip to content

Commit

Permalink
chore: improve some code documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
mlegner authored and jpcsmith committed Dec 14, 2023
1 parent 473a1c2 commit 1a8ab53
Show file tree
Hide file tree
Showing 15 changed files with 60 additions and 53 deletions.
6 changes: 3 additions & 3 deletions crates/scion-proto/src/address/host.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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),
}

Expand Down
2 changes: 1 addition & 1 deletion crates/scion-proto/src/address/ia.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down
9 changes: 5 additions & 4 deletions crates/scion-proto/src/address/isd.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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
///
Expand Down
15 changes: 9 additions & 6 deletions crates/scion-proto/src/datagram.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#![allow(missing_docs)]
//! Representation, encoding, and decoding of UDP datagrams.

use bytes::{Buf, BufMut, Bytes, BytesMut};

Expand All @@ -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].
Expand All @@ -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
Expand Down Expand Up @@ -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> {
Expand Down
7 changes: 2 additions & 5 deletions crates/scion-proto/src/packet/headers/address_header.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
Expand Down
10 changes: 5 additions & 5 deletions crates/scion-proto/src/path.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
}

Expand Down
18 changes: 9 additions & 9 deletions crates/scion-proto/src/path/dataplane.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand All @@ -23,7 +23,7 @@ pub enum PathType {
Epic,
/// Experimental Colibri path type.
Colibri,
/// Other, unrecognized path types
/// Other, unrecognized path types.
Other(u8),
}

Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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
}
Expand Down
6 changes: 3 additions & 3 deletions crates/scion-proto/src/path/epic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
4 changes: 3 additions & 1 deletion crates/scion-proto/src/path/error.rs
Original file line number Diff line number Diff line change
@@ -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 {
Expand Down Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion crates/scion-proto/src/path/metadata.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion crates/scion-proto/src/path/metadata/geo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
4 changes: 2 additions & 2 deletions crates/scion-proto/src/path/metadata/linktype.rs
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion crates/scion-proto/src/path/metadata/path_interface.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions crates/scion-proto/src/path/standard.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! A standard SCION path,
//! A standard SCION path.

use std::mem;

Expand All @@ -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);
}
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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()
}
Expand Down
12 changes: 8 additions & 4 deletions crates/scion-proto/src/reliable/common_header.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#![allow(missing_docs)]
//! Common header for the reliable relay protocol.

use std::net::{IpAddr, SocketAddr};

Expand All @@ -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),
}

Expand All @@ -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,
}

Expand Down Expand Up @@ -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,
Expand Down

0 comments on commit 1a8ab53

Please sign in to comment.