add some docs for internal-only listeners

src/listener/parsed_listener.rs

@@ -2,9 +2,17 @@
 use super::UnixListener;
 use super::{Listener, TcpListener};
 use crate::Server;
+
 use async_std::io;
 use std::fmt::{self, Display, Formatter};
 
+/// This is an enum that contains variants for each of the listeners
+/// that can be parsed from a string. This is used as the associated
+/// Listener type for the string-parsing
+/// [ToListener](crate::listener::ToListener) implementations
+///
+/// This is currently crate-visible only, and tide users are expected
+/// to create these through [ToListener](crate::ToListener) conversions.
 #[derive(Debug)]
 pub enum ParsedListener {
     #[cfg(unix)]

src/listener/tcp_listener.rs

@@ -9,6 +9,14 @@ use async_std::net::{self, SocketAddr, TcpStream};
 use async_std::prelude::*;
 use async_std::{io, task};
 
+/// This represents a tide [Listener](crate::listener::Listener) that
+/// wraps an [async_std::net::TcpListener]. It is implemented as an
+/// enum in order to allow creation of a tide::listener::TcpListener
+/// from a SocketAddr spec that has not yet been bound OR from a bound
+/// TcpListener.
+///
+/// This is currently crate-visible only, and tide users are expected
+/// to create these through [ToListener](crate::ToListener) conversions.
 #[derive(Debug)]
 pub enum TcpListener {
     FromListener(net::TcpListener),
@@ -30,7 +38,7 @@ impl TcpListener {
             Self::FromListener(listener) => Ok(listener),
             Self::FromAddrs(addrs, None) => Err(io::Error::new(
                 io::ErrorKind::AddrNotAvailable,
-                format!("unable to connect {:?}", addrs),
+                format!("unable to connect to {:?}", addrs),
             )),
         }
     }

src/listener/unix_listener.rs

@@ -9,6 +9,14 @@ use async_std::os::unix::net::{self, SocketAddr, UnixStream};
 use async_std::prelude::*;
 use async_std::{io, path::PathBuf, task};
 
+/// This represents a tide [Listener](crate::listener::Listener) that
+/// wraps an [async_std::os::unix::net::UnixListener]. It is implemented as an
+/// enum in order to allow creation of a tide::listener::UnixListener
+/// from a [PathBuf] that has not yet been opened/bound OR from a bound
+/// [async_std::os::unix::net::UnixListener].
+///
+/// This is currently crate-visible only, and tide users are expected
+/// to create these through [ToListener](crate::ToListener) conversions.
 #[derive(Debug)]
 pub enum UnixListener {
     FromPath(PathBuf, Option<net::UnixListener>),
@@ -30,7 +38,10 @@ impl UnixListener {
             Self::FromListener(listener) => Ok(listener),
             Self::FromPath(path, None) => Err(io::Error::new(
                 io::ErrorKind::AddrNotAvailable,
-                format!("unable to connect {}", path.to_str().unwrap_or("[unknown]")),
+                format!(
+                    "unable to connect to {}",
+                    path.to_str().unwrap_or("[unknown]")
+                ),
             )),
         }
     }