Module docs and comment formatting (v. important)

dns-transport/src/auto.rs

@@ -4,8 +4,11 @@ use dns::{Request, Response};
 use super::{Transport, Error, UdpTransport, TcpTransport};
 
 
-/// The **automatic transport**, which uses the UDP transport, then tries
-/// using the TCP transport if the first one fails.
+/// The **automatic transport**, which sends DNS wire data using the UDP
+/// transport, then tries using the TCP transport if the first one fails
+/// because the response wouldn't fit in a single UDP packet.
+///
+/// This is the default behaviour for many DNS clients.
 ///
 /// # Examples
 ///

dns-transport/src/https.rs

@@ -9,7 +9,8 @@ use dns::{Request, Response};
 use super::{Transport, Error};
 
 
-/// The **HTTPS transport**, which uses Hyper.
+/// The **HTTPS transport**, which sends DNS wire data inside HTTP packets
+/// encrypted with TLS, using TCP.
 ///
 /// # Examples
 ///

dns-transport/src/lib.rs

@@ -48,7 +48,7 @@ mod https;
 pub use self::https::HttpsTransport;
 
 
-/// The trait implemented by all four transport types.
+/// The trait implemented by all transport types.
 pub trait Transport {
 
     /// Convert the request to bytes, send it over the network, wait for a
@@ -56,7 +56,7 @@ pub trait Transport {
     ///
     /// # Errors
     ///
-    /// Returns an [`Error`] error if there's an I/O error sending or
+    /// Returns an `Error` error if there’s an I/O error sending or
     /// receiving data, or the DNS packet in the response contained invalid
     /// bytes and failed to parse, or if there was a protocol-level error for
     /// the TLS and HTTPS transports.
@@ -64,7 +64,7 @@ pub trait Transport {
 }
 
 /// Something that can go wrong making a DNS request.
-#[derive(Debug, From)]  // can't be PartialEq due to tokio error
+#[derive(Debug, From)]  // can’t be PartialEq due to std::io::Error
 pub enum Error {
 
     /// There was a problem with the network sending the request or receiving

dns-transport/src/tcp.rs

@@ -8,7 +8,7 @@ use dns::{Request, Response};
 use super::{Transport, Error};
 
 
-/// The **TCP transport**, which uses the stdlib.
+/// The **TCP transport**, which sends DNS wire data over a TCP stream.
 ///
 /// # Examples
 ///
@@ -33,10 +33,12 @@ use super::{Transport, Error};
 /// transport.send(&request);
 /// ```
 ///
-/// # Reference
+/// # References
 ///
-/// - [RFC 1035 §4.2.2](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
-/// - [RFC 7766](https://tools.ietf.org/html/rfc1035) — DNS Transport over TCP, Implementation Requirements (March 2016)
+/// - [RFC 1035 §4.2.2](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
+/// - [RFC 7766](https://tools.ietf.org/html/rfc1035) — DNS Transport over
+///   TCP, Implementation Requirements (March 2016)
 #[derive(Debug)]
 pub struct TcpTransport {
     addr: String,

dns-transport/src/tls.rs

@@ -10,7 +10,8 @@ use dns::{Request, Response};
 use super::{Transport, Error};
 
 
-/// The **TLS transport**, which uses Tokio.
+/// The **TLS transport**, which sends DNS wire data using TCP through an
+/// encrypted TLS connection.
 ///
 /// # Examples
 ///

dns-transport/src/udp.rs

@@ -6,7 +6,7 @@ use dns::{Request, Response};
 use super::{Transport, Error};
 
 
-/// The **UDP transport**, which uses the stdlib.
+/// The **UDP transport**, which sends DNS wire data inside a UDP datagram.
 ///
 /// # Examples
 ///

dns/src/record/a.rs

@@ -9,7 +9,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.4.1](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.4.1](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub struct A {
 

dns/src/record/aaaa.rs

@@ -9,7 +9,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 3596](https://tools.ietf.org/html/rfc3596) — DNS Extensions to Support IP Version 6 (October 2003)
+/// - [RFC 3596](https://tools.ietf.org/html/rfc3596) — DNS Extensions to
+///   Support IP Version 6 (October 2003)
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub struct AAAA {
 

dns/src/record/caa.rs

@@ -3,12 +3,14 @@ use log::*;
 use crate::wire::*;
 
 
-/// A **CAA** record. These allow domain names to specify which Certificate
-/// Authorities are allowed to issue certificates for the domain.
+/// A **CAA** _(certification authority authorization)_ record. These allow
+/// domain names to specify which Certificate Authorities are allowed to issue
+/// certificates for the domain.
 ///
 /// # References
 ///
-/// - [RFC 6844](https://tools.ietf.org/html/rfc6844) — DNS Certification Authority Authorization Resource Record (January 2013)
+/// - [RFC 6844](https://tools.ietf.org/html/rfc6844) — DNS Certification
+///   Authority Authorization Resource Record (January 2013)
 #[derive(PartialEq, Debug)]
 pub struct CAA {
 

dns/src/record/cname.rs

@@ -8,7 +8,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.1](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.3.1](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug)]
 pub struct CNAME {
 

dns/src/record/hinfo.rs

@@ -10,8 +10,10 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.2](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
-/// - [RFC 8482 §6](https://tools.ietf.org/html/rfc8482#section-6) — Providing Minimal-Sized Responses to DNS Queries That Have QTYPE=ANY (January 2019)
+/// - [RFC 1035 §3.3.2](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
+/// - [RFC 8482 §6](https://tools.ietf.org/html/rfc8482#section-6) — Providing
+///   Minimal-Sized Responses to DNS Queries That Have QTYPE=ANY (January 2019)
 #[derive(PartialEq, Debug)]
 pub struct HINFO {
 

dns/src/record/loc.rs

@@ -10,7 +10,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1876](https://tools.ietf.org/html/rfc1876) — A Means for Expressing Location Information in the Domain Name System (January 1996)
+/// - [RFC 1876](https://tools.ietf.org/html/rfc1876) — A Means for Expressing
+///   Location Information in the Domain Name System (January 1996)
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub struct LOC {
 
@@ -181,7 +182,7 @@ impl Position {
 impl Altitude {
     fn from_u32(input: u32) -> Self {
         let mut input = i64::from(input);
-        input -= 100_000_00;  // 100,000m
+        input -= 10_000_000;  // 100,000m
         let metres = input / 100;
         let centimetres = input % 100;
         Self { metres, centimetres }
@@ -224,7 +225,7 @@ impl fmt::Display for Direction {
 
 impl fmt::Display for Altitude {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        // Usually there's a space between the number and the unit, but
+        // Usually there’s a space between the number and the unit, but
         // spaces are already used to delimit segments in the record summary
         if self.centimetres == 0 {
             write!(f, "{}m", self.metres)

dns/src/record/mx.rs

@@ -9,7 +9,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.9](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.3.9](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug)]
 pub struct MX {
 

dns/src/record/naptr.rs

@@ -4,7 +4,14 @@ use crate::strings::{Labels, ReadLabels};
 use crate::wire::*;
 
 
-/// A **NAPTR** _(naming authority pointer)_ record,
+/// A **NAPTR** _(naming authority pointer)_ record, which holds a rule for
+/// the Dynamic Delegation Discovery System.
+///
+/// # References
+///
+/// - [RFC 3403](https://tools.ietf.org/html/rfc3403) — Dynamic Delegation
+///   Discovery System (DDDS) Part Three: The Domain Name System (DNS) Database
+///   (October 2002)
 #[derive(PartialEq, Debug)]
 pub struct NAPTR {
 

dns/src/record/ns.rs

@@ -9,7 +9,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.11](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.3.11](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug)]
 pub struct NS {
 

dns/src/record/opt.rs

@@ -28,7 +28,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 6891](https://tools.ietf.org/html/rfc6891) — Extension Mechanisms for DNS (April 2013)
+/// - [RFC 6891](https://tools.ietf.org/html/rfc6891) — Extension Mechanisms
+///   for DNS (April 2013)
 #[derive(PartialEq, Debug)]
 pub struct OPT {
 

dns/src/record/ptr.rs

@@ -14,7 +14,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.14](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.3.14](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug)]
 pub struct PTR {
 

dns/src/record/soa.rs

@@ -10,7 +10,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.13](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.3.13](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug)]
 pub struct SOA {
 

dns/src/record/srv.rs

@@ -9,7 +9,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 2782](https://tools.ietf.org/html/rfc2782) — A DNS RR for specifying the location of services (February 2000)
+/// - [RFC 2782](https://tools.ietf.org/html/rfc2782) — A DNS RR for
+///   specifying the location of services (February 2000)
 #[derive(PartialEq, Debug)]
 pub struct SRV {
 

dns/src/record/sshfp.rs

@@ -8,7 +8,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 4255](https://tools.ietf.org/html/rfc4255) — Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints (January 2006)
+/// - [RFC 4255](https://tools.ietf.org/html/rfc4255) — Using DNS to Securely
+///   Publish Secure Shell (SSH) Key Fingerprints (January 2006)
 #[derive(PartialEq, Debug)]
 pub struct SSHFP {
 

dns/src/record/tlsa.rs

@@ -8,7 +8,9 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// [RFC 6698](https://tools.ietf.org/html/rfc6698) — The DNS-Based Authentication of Named Entities (DANE) Transport Layer Security Protocol: TLSA (August 2012)
+/// - [RFC 6698](https://tools.ietf.org/html/rfc6698) — The DNS-Based
+///   Authentication of Named Entities (DANE) Transport Layer Security
+///   Protocol: TLSA (August 2012)
 #[derive(PartialEq, Debug)]
 pub struct TLSA {
 

dns/src/record/txt.rs

@@ -12,7 +12,8 @@ use crate::wire::*;
 ///
 /// # References
 ///
-/// - [RFC 1035 §3.3.14](https://tools.ietf.org/html/rfc1035) — Domain Names, Implementation and Specification (November 1987)
+/// - [RFC 1035 §3.3.14](https://tools.ietf.org/html/rfc1035) — Domain Names,
+///   Implementation and Specification (November 1987)
 #[derive(PartialEq, Debug)]
 pub struct TXT {
 

dns/src/types.rs

@@ -100,7 +100,7 @@ pub enum Answer {
 }
 
 
-/// A DNS record class. Of these, the only one that's in regular use anymore
+/// A DNS record class. Of these, the only one that’s in regular use anymore
 /// is the Internet class.
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub enum QClass {
@@ -158,6 +158,7 @@ pub struct Flags {
     pub error_code: Option<ErrorCode>,
 }
 
+
 /// A number representing the operation being performed.
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub enum Opcode {
@@ -173,26 +174,32 @@ pub enum Opcode {
 
 
 /// A code indicating an error.
+///
+/// # References
+///
+/// - [RFC 6895 §2.3](https://tools.ietf.org/html/rfc6895#section-2.3) — Domain
+///   Name System (DNS) IANA Considerations (April 2013)
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub enum ErrorCode {
 
-    /// The server was unable to interpret the oquery.
+    /// `FORMERR` — The server was unable to interpret the query.
     FormatError,
 
-    /// There was a problem with the server.
+    /// `SERVFAIL` — There was a problem with the server.
     ServerFailure,
 
-    /// The domain name referenced in the query does not exist.
+    /// `NXDOMAIN` — The domain name referenced in the query does not exist.
     NXDomain,
 
-    /// The server does not support one of the requested features.
+    /// `NotImp` — The server does not support one of the requested features.
     NotImplemented,
 
-    /// The server was able to interpret the query, but refused to fulfil it.
+    /// `Refused` — The server was able to interpret the query, but refused to
+    /// fulfil it.
     QueryRefused,
 
-    /// The server did not accept the EDNS version, or failed to verify a
-    /// signature.
+    /// `NotAuth` — The server did not accept the EDNS version, or failed to
+    /// verify a signature.
     BadVersion,
 
     /// An error code we don’t know what it is.

src/connect.rs

@@ -1,8 +1,12 @@
+//! Creating DNS transports based on the user’s input arguments.
+
 use dns_transport::*;
 
 use crate::resolve::Nameserver;
 
 
+/// A **transport type** creates a `Transport` that determines which protocols
+/// should be used to send and receive DNS wire data over the network.
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub enum TransportType {
 

src/main.rs

@@ -92,6 +92,7 @@ fn main() {
 }
 
 
+/// Runs dog with some options, returning the status to exit with.
 fn run(Options { requests, format, measure_time }: Options) -> i32 {
     use std::time::Instant;
 
@@ -136,8 +137,8 @@ fn run(Options { requests, format, measure_time }: Options) -> i32 {
 }
 
 
+/// The possible status numbers dog can exit with.
 mod exits {
-    #![allow(unused)]
 
     /// Exit code for when everything turns out OK.
     pub const SUCCESS: i32 = 0;
@@ -146,7 +147,7 @@ mod exits {
     pub const NETWORK_ERROR: i32 = 1;
 
     /// Exit code for when there is no result from the server when running in
-    /// short mode. This can be any received server error, not just NXDOMAIN.
+    /// short mode. This can be any received server error, not just `NXDOMAIN`.
     pub const NO_SHORT_RESULTS: i32 = 2;
 
     /// Exit code for when the command-line options are invalid.

src/options.rs

@@ -1,3 +1,5 @@
+//! Command-line option parsing.
+
 use std::ffi::OsStr;
 use std::fmt;
 

src/requests.rs

@@ -1,3 +1,5 @@
+//! Request generation based on the user’s input arguments.
+
 use dns::Labels;
 
 use crate::connect::TransportType;

src/resolve.rs

@@ -1,3 +1,5 @@
+//! Specifying the address of the DNS server to send requests to.
+
 use std::io;
 
 use log::*;

src/table.rs

@@ -1,4 +1,4 @@
-//! Tables of DNS response results.
+//! Rendering tables of DNS response results.
 
 use std::time::Duration;
 

src/txid.rs

@@ -1,3 +1,6 @@
+//! Transaction ID generation.
+
+
 /// A **transaction ID generator** is used to create unique ID numbers to
 /// identify each packet, as part of the DNS protocol.
 #[derive(PartialEq, Debug, Copy, Clone)]