From cae47b9bc24f8d5ffd147ddd3774348396060772 Mon Sep 17 00:00:00 2001
From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com>
Date: Sat, 30 Mar 2024 22:41:05 +0100
Subject: [PATCH] More RustDocs.

---
 src/zonetree/tree.rs  | 10 ++++++++++
 src/zonetree/types.rs | 13 +++++++++++++
 src/zonetree/walk.rs  |  2 ++
 src/zonetree/zone.rs  |  7 ++++++-
 4 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/src/zonetree/tree.rs b/src/zonetree/tree.rs
index 7ca432cca..9ece506b4 100644
--- a/src/zonetree/tree.rs
+++ b/src/zonetree/tree.rs
@@ -20,10 +20,12 @@ pub struct ZoneTree {
 }
 
 impl ZoneTree {
+    /// Creates an empty [`ZoneTree`].
     pub fn new() -> Self {
         Default::default()
     }
 
+    /// Gets a [`Zone`] for the given apex name and CLASS, if any.
     pub fn get_zone(
         &self,
         apex_name: &impl ToDname,
@@ -34,6 +36,10 @@ impl ZoneTree {
             .get_zone(apex_name.iter_labels().rev())
     }
 
+    /// Inserts the given [`Zone`].
+    ///
+    /// Returns a [`ZoneTreeModificationError`] if a zone with the same apex
+    /// and CLASS already exists in the tree.
     pub fn insert_zone(
         &mut self,
         zone: Zone,
@@ -44,6 +50,8 @@ impl ZoneTree {
         )
     }
 
+    /// Gets the closest matching [`Zone`] for the given QNAME and CLASS, if
+    /// any.
     pub fn find_zone(
         &self,
         qname: &impl ToDname,
@@ -52,10 +60,12 @@ impl ZoneTree {
         self.roots.get(class)?.find_zone(qname.iter_labels().rev())
     }
 
+    /// Returns an iterator over all of the [`Zone`]s in the tree.
     pub fn iter_zones(&self) -> ZoneSetIter {
         ZoneSetIter::new(self)
     }
 
+    /// Removes the specified [`Zone`], if any.
     pub fn remove_zone(
         &mut self,
         apex_name: &impl ToDname,
diff --git a/src/zonetree/types.rs b/src/zonetree/types.rs
index 4540cca27..e85cf22ef 100644
--- a/src/zonetree/types.rs
+++ b/src/zonetree/types.rs
@@ -11,12 +11,21 @@ use std::vec::Vec;
 
 //------------ Type Aliases --------------------------------------------------
 
+/// A [`Bytes`] backed [`Dname`].
 pub type StoredDname = Dname<Bytes>;
+
+/// A [`Bytes`] backed [`ZoneRecordData`].
 pub type StoredRecordData = ZoneRecordData<Bytes, StoredDname>;
+
+/// A [`Bytes`] backed [`Record`].`
 pub type StoredRecord = Record<StoredDname, StoredRecordData>;
 
 //------------ SharedRr ------------------------------------------------------
 
+/// A cheaply clonable resource record.
+///
+/// A [`Bytes`] backed resource record which is cheap to [`Clone`] because
+/// [`Bytes`] is cheap to clone.
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub struct SharedRr {
     ttl: Ttl,
@@ -24,18 +33,22 @@ pub struct SharedRr {
 }
 
 impl SharedRr {
+    /// Create a new [`SharedRr`] instance.
     pub fn new(ttl: Ttl, data: StoredRecordData) -> Self {
         SharedRr { ttl, data }
     }
 
+    /// Gets the type of this resource record.
     pub fn rtype(&self) -> Rtype {
         self.data.rtype()
     }
 
+    /// Gets the TTL of this resource record.
     pub fn ttl(&self) -> Ttl {
         self.ttl
     }
 
+    /// Gets a reference to the data of this resource record.
     pub fn data(&self) -> &StoredRecordData {
         &self.data
     }
diff --git a/src/zonetree/walk.rs b/src/zonetree/walk.rs
index 94743d779..21330084a 100644
--- a/src/zonetree/walk.rs
+++ b/src/zonetree/walk.rs
@@ -8,6 +8,8 @@ use super::Rrset;
 use crate::base::name::OwnedLabel;
 use crate::base::{Dname, DnameBuilder};
 
+/// A callback function invoked for each leaf node visited while walking a
+/// [`Zone`].
 pub type WalkOp = Box<dyn Fn(Dname<Bytes>, &Rrset) + Send + Sync>;
 
 struct WalkStateInner {
diff --git a/src/zonetree/zone.rs b/src/zonetree/zone.rs
index 8d6be05eb..d160b14b3 100644
--- a/src/zonetree/zone.rs
+++ b/src/zonetree/zone.rs
@@ -12,33 +12,38 @@ use super::in_memory::ZoneBuilder;
 use super::traits::WritableZone;
 use super::{ReadableZone, StoredDname, ZoneStore};
 
-// TODO: Delete Zone, rename ZoneStore to Zone (and make ZoneSetNode generic?)
 //------------ Zone ----------------------------------------------------------
 
+/// A single DNS zone.
 #[derive(Debug)]
 pub struct Zone {
     store: Arc<dyn ZoneStore>,
 }
 
 impl Zone {
+    /// Creates a new [`Zone`] instance with the given data.
     pub fn new(data: impl ZoneStore + 'static) -> Self {
         Zone {
             store: Arc::new(data),
         }
     }
 
+    /// Gets the CLASS of this zone.
     pub fn class(&self) -> Class {
         self.store.class()
     }
 
+    /// Gets the apex name of this zone.
     pub fn apex_name(&self) -> &StoredDname {
         self.store.apex_name()
     }
 
+    /// Gets a read interface to this zone.
     pub fn read(&self) -> Box<dyn ReadableZone> {
         self.store.clone().read()
     }
 
+    /// Gets a write interface to this zone.
     pub fn write(
         &self,
     ) -> Pin<Box<dyn Future<Output = Box<dyn WritableZone>>>> {