docs(Mist): Normalise doc-comment sections and add missing module-level docs

Standardise doc-comment formatting across all six public source files. The
primary change is upgrading section headings from single-hash to double-hash
(`# Parameters` → `## Parameters`, `# Returns` → `## Returns`, `# Example` →
`## Example`) so they nest correctly under the outer item-level doc comment
delimiter.

Add module-level doc comments with `## Functions` or `## Types` listings to
Resolver.rs, Server.rs, and Zone.rs, matching the pattern already established
in the crate's earlier source files. Add missing `## Parameters` and `## Returns`
sections to `LandResolver`, `LandDnsResolver::New`, `LandDnsResolver::new`,
`SharedSecret::random`, `SharedSecret::as_hex`, and `reqwest::dns::Resolve::resolve`.
Add `## Errors` sections to `Serve` and `ServeSync` documenting the failure
conditions (non-loopback bind, hickory runtime errors).

Fix indentation in doc-example code blocks in Library.rs (tabs to spaces) and
mark a TODO-style note in ForwardSecurity.rs with the currently authorised
allowlist domain (`update.editor.land`).

No functional changes — documentation and formatting only.

Author: NikolaRHristov

Source/ForwardSecurity.rs

@@ -19,9 +19,10 @@ use hickory_proto::rr::Name;
 /// Returns the default DNS forward allowlist.
 ///
 /// Domains in the allowlist may be forwarded to upstream DNS servers.
-/// All other domains receive `REFUSED`.
+/// All other domains receive `REFUSED`. Currently authorizes
+/// `update.editor.land` as the sole forwarded domain.
 ///
-/// # Returns
+/// ## Returns
 ///
 /// An iterator of parseable `Name` values for allowed forward domains.
 pub fn DefaultForwardAllowlist() -> impl Iterator<Item = Result<Name>> {

Source/Library.rs

@@ -86,7 +86,6 @@ pub mod WebSocket;
 ///
 /// ```rust
 /// use Mist::dns_port;
-///
 /// let port = dns_port();
 /// ```
 pub static DNS_PORT:OnceCell<u16> = OnceCell::new();
@@ -96,20 +95,19 @@ pub static DNS_PORT:OnceCell<u16> = OnceCell::new();
 /// Provides the port that the DNS server is listening on, or `0` if the
 /// server has not been started yet.
 ///
-/// # Returns
+/// ## Returns
 ///
-/// The port number (0-65535), or 0 if the server hasn't started.
+/// The port number (0–65535), or `0` if the server hasn't been started.
 ///
-/// # Example
+/// ## Example
 ///
 /// ```rust
 /// use Mist::dns_port;
-///
 /// let port = dns_port();
 /// if port > 0 {
-/// 	println!("DNS server is running on port {}", port);
+///     println!("DNS server is running on port {}", port);
 /// } else {
-/// 	println!("DNS server has not been started");
+///     println!("DNS server has not been started");
 /// }
 /// ```
 pub fn dns_port() -> u16 { *DNS_PORT.get().unwrap_or(&0) }
@@ -126,28 +124,28 @@ pub fn dns_port() -> u16 { *DNS_PORT.get().unwrap_or(&0) }
 /// The DNS server runs in the background and can be stopped by dropping
 /// the application.
 ///
-/// # Parameters
+/// ## Parameters
 ///
-/// * `preferred_port` - The preferred port number to use. If this port is
+/// * `preferred_port` — The preferred port number to use. If this port is
 ///   already in use, portpicker will find an alternative available port.
 ///
-/// # Returns
+/// ## Returns
 ///
-/// Returns `Ok(port)` with the port number the server is listening on,
+/// `Ok(port)` with the port number the server is listening on,
 /// or an error if the server failed to start.
 ///
-/// # Example
+/// ## Example
 ///
 /// ```rust,no_run
 /// use Mist::start;
 ///
 /// #[tokio::main]
 /// async fn main() -> anyhow::Result<()> {
-/// 	// Start DNS server, preferring port 5353
-/// 	let port = start(5353)?;
-/// 	println!("DNS server started on port {}", port);
-/// 	tokio::signal::ctrl_c().await?;
-/// 	Ok(())
+///     // Start DNS server, preferring port 5353
+///     let port = start(5353)?;
+///     println!("DNS server started on port {}", port);
+///     tokio::signal::ctrl_c().await?;
+///     Ok(())
 /// }
 /// ```
 pub fn start(preferred_port:u16) -> Result<u16> {

Source/Resolver.rs

@@ -3,16 +3,30 @@
 //! Provides DNS resolution for the CodeEditorLand private network.
 //! Routes `*.editor.land` queries to loopback; other domains fall back
 //! to system DNS.
+//!
+//! ## Types
+//!
+//! * [`TokioResolver`] — Stub resolver that queries the local DNS server.
+//! * [`LandDnsResolver`] — Secured resolver for `reqwest` DNS override.
 
 use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 
 /// Stub DNS resolver type.
 ///
 /// In production this wraps a real hickory-client resolver connected
-/// to the local DNS server.
+/// to the local DNS server. Currently a zero-size placeholder awaiting
+/// integration with the running Mist server port.
 pub struct TokioResolver;
 
 /// Builds a `TokioResolver` stub that queries the local DNS server.
+///
+/// ## Parameters
+///
+/// * `_DNSPort` — Port number of the running Mist server (currently unused).
+///
+/// ## Returns
+///
+/// A new `TokioResolver` instance.
 pub fn LandResolver(_DNSPort:u16) -> TokioResolver { TokioResolver }
 
 /// Secured DNS resolver for use with `reqwest`'s DNS override.
@@ -22,21 +36,51 @@ pub fn LandResolver(_DNSPort:u16) -> TokioResolver { TokioResolver }
 pub struct LandDnsResolver;
 
 impl LandDnsResolver {
-	/// Builds a new `LandDnsResolver` connected to the given DNS port.
+	/// Builds a new `LandDnsResolver` connected to the given DNS port (PascalCase).
+	///
+	/// Matches the project's naming convention for constructors.
+	/// See also [`new`](Self::new).
+	///
+	/// ## Parameters
+	///
+	/// * `_Port` — Port number of the running Mist server (currently unused).
+	///
+	/// ## Returns
 	///
-	/// This is the PascalCase variant, matching the project's naming
-	/// convention for constructors. See also [`new`](Self::new).
+	/// A new `LandDnsResolver` instance.
 	pub fn New(_Port:u16) -> Self { Self }
 
 	/// Builds a new `LandDnsResolver` (snake_case alias for reqwest).
 	///
-	/// This variant exists for compatibility with the `reqwest::dns::Resolve`
+	/// Exists for compatibility with the `reqwest::dns::Resolve`
 	/// trait's expected construction pattern. Both this and [`New`](Self::New)
 	/// are identical.
+	///
+	/// ## Parameters
+	///
+	/// * `_Port` — Port number of the running Mist server (currently unused).
+	///
+	/// ## Returns
+	///
+	/// A new `LandDnsResolver` instance.
 	pub fn new(_Port:u16) -> Self { Self }
 }
 
 impl reqwest::dns::Resolve for LandDnsResolver {
+	/// Resolves a domain name to IP addresses.
+	///
+	/// Routes `*.editor.land` queries to `127.0.0.1`. Returns an empty
+	/// iterator for all other domains so that `reqwest` falls through to
+	/// its system DNS resolver.
+	///
+	/// ## Parameters
+	///
+	/// * `Name` — The domain name to resolve.
+	///
+	/// ## Returns
+	///
+	/// A resolving future that yields socket addresses (loopback for
+	/// `editor.land` domains, empty otherwise).
 	fn resolve(&self, Name:reqwest::dns::Name) -> reqwest::dns::Resolving {
 		let NameString = Name.as_str().to_string();
 

Source/Server.rs

@@ -2,6 +2,12 @@
 //!
 //! Builds and serves the private DNS catalog for CodeEditorLand.
 //! Binds exclusively to loopback (`127.0.0.1`) to prevent LAN exposure.
+//!
+//! ## Functions
+//!
+//! * [`BuildCatalog`] — Constructs the DNS catalog with `editor.land` zone.
+//! * [`Serve`] — Runs the async DNS server on a loopback port.
+//! * [`ServeSync`] — Blocking convenience wrapper around [`Serve`].
 
 use std::{
 	net::{IpAddr, Ipv4Addr, SocketAddr},
@@ -25,24 +31,25 @@ use hickory_server::{
 };
 use tokio::net::UdpSocket;
 
-/// Buffer capacity for outgoing DNS TCP responses per connection. 65 535 is
-/// the upper bound a single DNS message can reach over TCP (the 16-bit
-/// length prefix cap from RFC 1035 §4.2.2). Picking the cap avoids any
-/// truncation for zone-transfer or large TXT responses while staying well
-/// within memory for the dozen-or-so concurrent connections a local
-/// `editor.land` catalog ever sees.
+/// Buffer capacity for outgoing DNS TCP responses per connection.
+///
+/// 65 535 is the upper bound a single DNS message can reach over TCP
+/// (the 16-bit length prefix cap from RFC 1035 §4.2.2). Picking the cap
+/// avoids any truncation for zone-transfer or large TXT responses while
+/// staying well within memory for the dozen-or-so concurrent connections
+/// a local `editor.land` catalog ever sees.
 const DNS_TCP_RESPONSE_BUFFER_SIZE:usize = 65_535;
 
 /// Builds a DNS catalog for the CodeEditorLand private network.
 ///
 /// Creates a catalog with an authoritative zone for `editor.land` that
 /// resolves all queries locally to loopback addresses.
 ///
-/// # Parameters
+/// ## Parameters
 ///
-/// * `_DNSPort` — Unused, reserved for future port-based catalog configuration.
+/// * `_DNSPort` — Reserved for future port-based catalog configuration.
 ///
-/// # Returns
+/// ## Returns
 ///
 /// A `Catalog` configured with the `editor.land` zone.
 pub fn BuildCatalog(_DNSPort:u16) -> Result<Catalog> {
@@ -77,14 +84,19 @@ pub fn BuildCatalog(_DNSPort:u16) -> Result<Catalog> {
 /// Binds to `127.0.0.1:{Port}` for both UDP and TCP. Validates that the
 /// socket is bound to a loopback address before accepting connections.
 ///
-/// # Parameters
+/// ## Parameters
 ///
 /// * `Catalog` — The DNS catalog (zone configuration) to serve.
 /// * `Port` — The loopback port number to bind to.
 ///
-/// # Returns
+/// ## Returns
 ///
 /// `Ok(())` on graceful shutdown, or an error if binding or serving fails.
+///
+/// ## Errors
+///
+/// Returns an error if the socket binds to a non-loopback address or
+/// if the hickory-server runtime encounters a failure.
 pub async fn Serve(Catalog:Catalog, Port:u16) -> Result<()> {
 	let Address:SocketAddr = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), Port);
 
@@ -176,14 +188,19 @@ pub async fn Serve(Catalog:Catalog, Port:u16) -> Result<()> {
 /// Creates a temporary Tokio runtime and runs [`Serve`] on it. Useful for
 /// threads or environments that do not manage their own async runtime.
 ///
-/// # Parameters
+/// ## Parameters
 ///
 /// * `Catalog` — The DNS catalog (zone configuration) to serve.
 /// * `Port` — The loopback port number to bind to.
 ///
-/// # Returns
+/// ## Returns
 ///
 /// `Ok(())` on graceful shutdown, or an error if binding or serving fails.
+///
+/// ## Errors
+///
+/// Propagates errors from [`Serve`], including binding failures and
+/// non-loopback address rejections.
 pub fn ServeSync(Catalog:Catalog, Port:u16) -> Result<()> {
 	let Runtime = tokio::runtime::Runtime::new()?;
 

Source/WebSocket.rs

@@ -77,14 +77,23 @@ use tokio_tungstenite::{
 	},
 };
 
-/// Per-spawn shared secret for WebSocket connection auth.
+/// Per-spawn shared secret for WebSocket connection authentication.
+///
+/// A cryptographically random 32-byte value used to authenticate
+/// WebSocket upgrade requests from native clients. Exchange happens
+/// out-of-band (environment variable from Mountain to Cocoon,
+/// Tauri invoke from Mountain to Sky).
 #[derive(Clone)]
 pub struct SharedSecret(pub [u8; 32]);
 
 impl SharedSecret {
 	/// Generates a cryptographically random 32-byte shared secret.
 	///
 	/// Uses the thread-local RNG from `rand` 0.10 via `rand::random`.
+	///
+	/// ## Returns
+	///
+	/// A new `SharedSecret` with 32 random bytes.
 	pub fn random() -> Self {
 		// rand 0.10: `rand::random::<[u8; N]>()` fills via the
 		// thread-local RNG without needing the deprecated
@@ -97,6 +106,10 @@ impl SharedSecret {
 	/// Each byte is encoded as two hexadecimal characters, producing a
 	/// 64-character string. Useful for transmitting the secret over HTTP
 	/// headers or environment variables.
+	///
+	/// ## Returns
+	///
+	/// A 64-character hex string.
 	pub fn as_hex(&self) -> String { hex::encode(self.0) }
 
 	/// Parses a hex-encoded string back into a `SharedSecret`.

Source/Zone.rs

@@ -3,6 +3,12 @@
 //! Provides DNS zone configuration for the CodeEditorLand private network.
 //! Creates an authoritative zone for `editor.land` that resolves to
 //! loopback addresses.
+//!
+//! ## Functions
+//!
+//! * [`EditorLandZone`] — Generates the zone records (SOA, NS, A).
+//! * [`EditorLandAuthority`] — Builds an `InMemoryZoneHandler` for `editor.land`.
+//! * [`CustomAuthority`] — Builds a handler for an arbitrary DNS origin.
 
 use anyhow::Result;
 use hickory_proto::rr::{
@@ -26,7 +32,7 @@ use hickory_server::{
 ///
 /// All `*.editor.land` domains resolve to `127.x.x.x` (loopback).
 ///
-/// # Returns
+/// ## Returns
 ///
 /// A vector of DNS records (SOA, NS, A) for the `editor.land` zone.
 pub fn EditorLandZone() -> Result<Vec<Record>> {
@@ -85,7 +91,10 @@ pub fn EditorLandZone() -> Result<Vec<Record>> {
 
 /// Builds an `InMemoryZoneHandler` for the `editor.land` zone.
 ///
-/// # Returns
+/// Creates a primary zone authority that serves the `editor.land` domain
+/// with AXFR transfers disabled.
+///
+/// ## Returns
 ///
 /// An `InMemoryZoneHandler` configured as primary for `editor.land`.
 pub fn EditorLandAuthority() -> Result<InMemoryZoneHandler<TokioRuntimeProvider>> {
@@ -101,13 +110,13 @@ pub fn EditorLandAuthority() -> Result<InMemoryZoneHandler<TokioRuntimeProvider>
 
 /// Builds an `InMemoryZoneHandler` for a custom origin with specified records.
 ///
-/// # Parameters
+/// ## Parameters
 ///
 /// * `Origin` — The DNS origin name (e.g. `example.com.`).
 /// * `_Records` — DNS records for the zone (currently unused; the handler
 ///   is created empty regardless).
 ///
-/// # Returns
+/// ## Returns
 ///
 /// An `InMemoryZoneHandler` configured as primary for the given origin.
 pub fn CustomAuthority(Origin:&Name, _Records:Vec<Record>) -> Result<InMemoryZoneHandler<TokioRuntimeProvider>> {