From ba65ca491346925f51f66a5f58d0555d99258a85 Mon Sep 17 00:00:00 2001
From: Jacob Rothstein <hi@jbr.me>
Date: Mon, 13 Jul 2020 16:40:39 -0700
Subject: [PATCH] add some docs for internal-only listeners

---
 src/listener/parsed_listener.rs |  8 ++++++++
 src/listener/tcp_listener.rs    | 10 +++++++++-
 src/listener/unix_listener.rs   | 13 ++++++++++++-
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/src/listener/parsed_listener.rs b/src/listener/parsed_listener.rs
index f8b1dd406..c98dc98ef 100644
--- a/src/listener/parsed_listener.rs
+++ b/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)]
diff --git a/src/listener/tcp_listener.rs b/src/listener/tcp_listener.rs
index d640a7e56..f6364fa3d 100644
--- a/src/listener/tcp_listener.rs
+++ b/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),
             )),
         }
     }
diff --git a/src/listener/unix_listener.rs b/src/listener/unix_listener.rs
index 0672991d0..cea1559c4 100644
--- a/src/listener/unix_listener.rs
+++ b/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]")
+                ),
             )),
         }
     }