Briefly document rabbit_reader records

2 files changed, 81 insertions, 10 deletions

diff --git a/src/rabbit_queue_collector.erl b/src/rabbit_queue_collector.erl
index 70a4da1e47..1201904ede 100644
--- a/src/rabbit_queue_collector.erl
+++ b/src/rabbit_queue_collector.erl
@@ -16,6 +16,9 @@
 
 -module(rabbit_queue_collector).
 
+%% Queue collector keeps track of exclusive queues and cleans them
+%% up e.g. when their connection is closed.
+
 -behaviour(gen_server).
 
 -export([start_link/1, register/2, delete_all/1]).
diff --git a/src/rabbit_reader.erl b/src/rabbit_reader.erl
index c8d798c5a7..f28f6ab0fb 100644
--- a/src/rabbit_reader.erl
+++ b/src/rabbit_reader.erl
@@ -38,16 +38,84 @@
 
 %%--------------------------------------------------------------------------
 
--record(v1, {parent, sock, connection, callback, recv_len, pending_recv,
-             connection_state, helper_sup, queue_collector, heartbeater,
-             stats_timer, channel_sup_sup_pid, channel_count, throttle}).
-
--record(connection, {name, host, peer_host, port, peer_port,
-                     protocol, user, timeout_sec, frame_max, channel_max, vhost,
-                     client_properties, capabilities,
-                     auth_mechanism, auth_state, connected_at}).
-
--record(throttle, {alarmed_by, last_blocked_by, last_blocked_at}).
+-record(v1, {
+          %% parent process
+          parent,
+          %% socket
+          sock,
+          %% connection state, see connection record
+          connection,
+          callback,
+          recv_len,
+          pending_recv,
+          %% pre_init | securing | running | blocking | blocked | closing | closed | {become, F}
+          connection_state,
+          %% see comment in rabbit_connection_sup:start_link/0
+          helper_sup,
+          %% takes care of cleaning up exclusive queues,
+          %% see rabbit_queue_collector
+          queue_collector,
+          %% sends and receives heartbeat frames,
+          %% see rabbit_heartbeat
+          heartbeater,
+          %% timer used to emit statistics
+          stats_timer,
+          %% channel supervisor
+          channel_sup_sup_pid,
+          %% how many channels this connection has
+          channel_count,
+          %% throttling state, for both
+          %% credit- and resource-driven flow control
+          throttle}).
+
+-record(connection, {
+          %% e.g. <<"127.0.0.1:55054 -> 127.0.0.1:5672">>
+          name,
+          %% server host
+          host,
+          %% client host
+          peer_host,
+          %% server port
+          port,
+          %% client port
+          peer_port,
+          %% protocol framing implementation module,
+          %% e.g. rabbit_framing_amqp_0_9_1
+          protocol,
+          user,
+          %% heartbeat timeout value used, 0 means
+          %% heartbeats are disabled
+          timeout_sec,
+          %% maximum allowed frame size,
+          %% see frame_max in the AMQP 0-9-1 spec
+          frame_max,
+          %% greatest channel number allowed,
+          %% see channel_max in the AMQP 0-9-1 spec
+          channel_max,
+          vhost,
+          %% client name, version, platform, etc
+          client_properties,
+          %% what lists protocol extensions
+          %% does this client support?
+          capabilities,
+          %% authentication mechanism used
+          %% as a pair of {Name, Module}
+          auth_mechanism,
+          %% authentication mechanism state,
+          %% initialised by rabbit_auth_mechanism:init/1
+          %% implementations
+          auth_state,
+          %% time of connection
+          connected_at}).
+
+-record(throttle, {
+  %% list of active alarms
+  alarmed_by,
+  %% flow | resource
+  last_blocked_by,
+  %% never | timestamp()
+  last_blocked_at
+}).
 
 -define(STATISTICS_KEYS, [pid, recv_oct, recv_cnt, send_oct, send_cnt,
                           send_pend, state, channels]).