From d7edd1960ef43187ba2d91c0f4b177adfc37b590 Mon Sep 17 00:00:00 2001
From: Jason Volk <jason@zemos.net>
Date: Sat, 1 Jun 2019 15:01:19 -0700
Subject: [PATCH] ircd::net::listener: Add some doc comments on the structure.

---
 include/ircd/net/acceptor.h |  1 +
 include/ircd/net/ipport.h   |  4 ++--
 include/ircd/net/listener.h | 11 +++++++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/include/ircd/net/acceptor.h b/include/ircd/net/acceptor.h
index 7e1f5a908..fb70037e0 100644
--- a/include/ircd/net/acceptor.h
+++ b/include/ircd/net/acceptor.h
@@ -16,6 +16,7 @@
 // is part of the <ircd/asio.h> stack which can be included in your
 // definition file if you need low level access to this acceptor API.
 
+/// Implementation to net::listener. See listener.h for additional interface.
 struct ircd::net::acceptor
 :std::enable_shared_from_this<struct ircd::net::acceptor>
 {
diff --git a/include/ircd/net/ipport.h b/include/ircd/net/ipport.h
index 1648cd566..9d6231ad9 100644
--- a/include/ircd/net/ipport.h
+++ b/include/ircd/net/ipport.h
@@ -55,8 +55,8 @@ struct ircd::net::ipport
 	explicit operator bool() const;
 	bool operator!() const             { return !static_cast<bool>(*this);     }
 
-	explicit operator const ipaddr &() const;
-	explicit operator ipaddr &();
+	operator const ipaddr &() const;
+	operator ipaddr &();
 
 	template<class iparg> ipport(iparg&&, const uint16_t &port);
 	template<class iparg> ipport(iparg&&, const string_view &port);
diff --git a/include/ircd/net/listener.h b/include/ircd/net/listener.h
index 3cf0264a2..14104facb 100644
--- a/include/ircd/net/listener.h
+++ b/include/ircd/net/listener.h
@@ -33,6 +33,17 @@ namespace ircd::net
 	bool stop(acceptor &);
 }
 
+/// This object is a wrapper interface to the internal net::acceptor object
+/// which contains boost assets which we cannot forward declare here. It
+/// implicitly converts as a reference to the internal acceptor. Users wishing
+/// to listen on a network interface for incoming connections create and hold
+/// an instance of this object.
+///
+/// The configuration is provided in JSON. The operations are asynchronous on
+/// the main stack and connected sockets are called back in callback. There is
+/// also a proffer callback which is made as early as possible (before the SSL
+/// handshake, and ideally if the platform supports it before a SYN-ACK) to
+/// reject connections by returning false.
 struct ircd::net::listener
 {
 	using callback = std::function<void (listener &, const std::shared_ptr<socket> &)>;