Docs

2 files changed, 36 insertions, 0 deletions

diff --git a/src/tcp_listener.erl b/src/tcp_listener.erl
index 571622c80d..ce0b38b35c 100644
--- a/src/tcp_listener.erl
+++ b/src/tcp_listener.erl
@@ -16,6 +16,35 @@
 
 -module(tcp_listener).
 
+%% Represents a running TCP listener (a process that listens for inbound
+%% TCP or TLS connections). Every protocol supported typically has one
+%% or two listeners, plain TCP and (optionally) TLS, but there can
+%% be more, e.g. when multiple network interfaces are involved.
+%%
+%% A listener has 5 properties (is a tuple of 5):
+%%
+%%  * IP address
+%%  * Port
+%%  * Label (human-friendly name, e.g. AMQP 0-9-1)
+%%  * Startup callback
+%%  * Shutdown callback
+%%
+%% Listeners use Ranch in embedded mode to accept and "bridge" client
+%% connections with protocol entry points such as rabbit_reader.
+%%
+%% Listeners are tracked in a Mnesia table so that they can be
+%%
+%%  * Shut down
+%%  * Listed (e.g. in the management UI)
+%%
+%% Every tcp_listener process has callbacks that are executed on start
+%% and termination. Those must take care of listener registration
+%% among other things.
+%%
+%% Listeners are supervised by tcp_listener_sup (one supervisor per protocol).
+%%
+%% See also rabbit_networking and tcp_listener_sup.
+
 -behaviour(gen_server).
 
 -export([start_link/5]).
diff --git a/src/tcp_listener_sup.erl b/src/tcp_listener_sup.erl
index 54da154d8d..4df8a45ac1 100644
--- a/src/tcp_listener_sup.erl
+++ b/src/tcp_listener_sup.erl
@@ -16,6 +16,13 @@
 
 -module(tcp_listener_sup).
 
+%% Supervises TCP listeners. There is a separate supervisor for every
+%% protocol. In case of AMQP 0-9-1, it resides under rabbit_sup. Plugins
+%% that provide protocol support (e.g. STOMP) have an instance of this supervisor in their
+%% app supervision tree.
+%%
+%% See also rabbit_networking and tcp_listener.
+
 -behaviour(supervisor).
 
 -export([start_link/9, start_link/10]).