improve explanations of things and fix layout

1 files changed, 70 insertions, 65 deletions

diff --git a/docs/rabbitmq.sample.config b/docs/rabbitmq.sample.config
index 178ce751..eb62285f 100644
--- a/docs/rabbitmq.sample.config
+++ b/docs/rabbitmq.sample.config
@@ -10,7 +10,7 @@
    %% Network Connectivity
    %%
 
-   %% Configure AMQP to listen on ports.
+   %% Configure AMQP to listen on specific ports.
    %% {tcp_listeners, [5672, 5673]},
 
    %% Socket options.
@@ -25,7 +25,7 @@
    %%                       {nodelay,       true},
    %%                       {exit_on_close, false}]},
 
-   %% Configure SSL to listen on ports.
+   %% Configure SSL to listen on specific ports.
    %% {ssl_listeners, [5674, 5675]},
 
    %% SSL options (see http://www.rabbitmq.com/ssl.html).
@@ -35,13 +35,13 @@
    %%                {verify, verify_peer},
    %%                {fail_if_no_peer_cert, true}]},
 
-   %% Max permissible size of a frame (in bytes).
+   %% Set the max permissible size of an AMQP frame (in bytes).
    %% {frame_max, 131072},
 
-   %% Heartbeat delay (in seconds).
+   %% Set the default AMQP heartbeat delay (in seconds).
    %% {heartbeat, 600},
 
-   %% Let the log level for connection logging.
+   %% Set the level for connection logging.
    %% {log_levels, [{connection, info}]},
 
    %%
@@ -51,10 +51,10 @@
    %% Set available auth mechanisms.
    %% {auth_mechanisms, ['PLAIN', 'AMQPLAIN']},
 
-   %% To enable auth-mechanism-ssl.
+   %% To enable auth-mechanism-ssl, add or replace the above with
    %% {auth_mechanisms, ['EXTERNAL']},
 
-   %% Set Available authentication databases.
+   %% Set the authentication database to use.
    %% {auth_backends, [rabbit_auth_backend_internal]},
 
    %% Or to enable the LDAP backend.
@@ -66,17 +66,18 @@
    %% User name to create on first start.
    %% {default_user, <<"guest">>},
 
-   %% Password for default user.
+   %% Password for the default user.
    %% {default_pass, <<"guest">>},
 
    %% Tags for default user.
    %% {default_user_tags, [administrator]},
 
-   %% Permissions for default user.
+   %% Set up access control (permissions) for the default user.
+   %% See http://www.rabbitmq.com/access-control.html for more details.
    %% {default_permissions, [<<".*">>, <<".*">>, <<".*">>]},
 
    %%
-   %% Resource Limits & Flow Control
+   %% Resource Limits & Flow Control.
    %%
    %% See http://www.rabbitmq.com/memory.html for more details.
    %%
@@ -90,7 +91,7 @@
    %% Alternatively, set disk free limit relative to total RAM.
    %% {disk_free_limit, {mem_relative, 1.0}},
 
-   %% Override file handle limits.
+   %% Override the file handle limit.
    %% {file_handles_high_watermark, 10000000},
 
    %%
@@ -167,23 +168,21 @@
   [{shovels,
     [%% A named shovel worker.
      %% {my_first_shovel,
-     %%  [{sources,
-     %%    [{brokers, [
-     %% URI(s) of source broker(s).
-     %%                "amqp://user:password@host.domain/my_vhost"
-     %%               ]},
-
-     %% Declarations we want to ensure are present on the
-     %% source broker(s).
+     %%  [
+
+     %% List the source broker(s) from which to consume.
+
+     %%   {sources,
+     %%    [%% URI(s) and pre-declarations for all source broker(s).
+     %%     {brokers, ["amqp://user:password@host.domain/my_vhost"]},
      %%     {declarations, []}
      %%    ]},
 
+     %% List the destination broker(s) to publish to.
+
      %%   {destinations,
      %%    [%% A singular version of the 'brokers' element.
      %%     {broker, "amqp://"},
-
-     %% Declarations we want to ensure are present on
-     %% the destination broker(s).
      %%     {declarations, []}
      %%    ]},
 
@@ -217,23 +216,24 @@
  %% See http://www.rabbitmq.com/stomp.html for details
  %% ----------------------------------------------------------------------------
 
- {rabbitmq_stomp, [%% Listen only on localhost (ipv4 & ipv6) on port 61613.
-                   %% {tcp_listeners, [{"127.0.0.1", 61612},
-                   %%                  {"::1",       61612}]},
+ {rabbitmq_stomp,
+  [%% Listen only on localhost (ipv4 & ipv6) on a specific port.
+   %% {tcp_listeners, [{"127.0.0.1", 61612},
+   %%                  {"::1",       61612}]},
 
-                   %% Listen for SSL connections on 61613.
-                   %% {ssl_listeners, [61613]},
+   %% Listen for SSL connections on a specific port.
+   %% {ssl_listeners, [61613]},
 
-                   %% Extract name from client certificate when using SSL.
-                   %% {ssl_cert_login, true},
+   %% Extract name from client certificate when using SSL.
+   %% {ssl_cert_login, true},
 
-                   %% Use cn instead of dn when reading from the SSL cert.
-                   %%                , {ssl_cert_login_from, common_name}.
+   %% Use cn instead of dn when reading from the SSL cert.
+   %% {ssl_cert_login_from, common_name},
 
-                   %% Set a default user and password.
-                   %% {default_user, [{login, "guest"},
-                   %%                 {passcode, "guest"}]}
-                  ]},
+   %% Set a default user name and password.
+   %% {default_user, [{login, "guest"},
+   %%                 {passcode, "guest"}]}
+  ]},
 
  %% ----------------------------------------------------------------------------
  %% RabbiMQ MQTT Adapter
@@ -241,36 +241,38 @@
  %% See http://hg.rabbitmq.com/rabbitmq-mqtt/file/stable/README.md for details
  %% ----------------------------------------------------------------------------
 
- {rabbitmq_mqtt, [%% Set the default user name and password.
-                  %% {default_user, <<"guest">>},
-                  %% {default_pass, <<"guest">>},
+ {rabbitmq_mqtt,
+  [%% Set the default user name and password.
+   %% {default_user, <<"guest">>},
+   %% {default_pass, <<"guest">>},
 
-                  %% Enable anonymous access.
-                  %% {allow_anonymous, true},
+   %% Enable anonymous access.
+   %% {allow_anonymous, true},
 
-                  %% Specify the vhost.
-                  %% {vhost, <<"/">>},
+   %% Specify the vhost to which the adapter connects.
+   %% {vhost, <<"/">>},
 
-                  %% Specify the exchange.
-                  %% {exchange, <<"amq.topic">>},
+   %% Specify the exchange to which messages from MQTT clients are published.
+   %% {exchange, <<"amq.topic">>},
 
-                  %% Specify TTL for subscriptions.
-                  %% {subscription_ttl, 1800000},
+   %% Specify TTL (time to live) to control the lifetime of non-clean sessions.
+   %% {subscription_ttl, 1800000},
 
-                  %% Set prefetch count.
-                  %% {prefetch, 10},
+   %% Set the prefetch count (governing the maximum number of unacknowledged
+   %%  messages that will be delivered).
+   %% {prefetch, 10},
 
-                  %% TCP/SSL Configuration.
-                  %% {ssl_listeners, []},
-                  %% {tcp_listeners,    [1883]},
+   %% TCP/SSL Configuration (as per the broker configuration)
+   %% {ssl_listeners, []},
+   %% {tcp_listeners, [1883]},
 
-                  %% TCP/Socket options.
-                  %% {tcp_listen_options, [binary,
-                  %%                       {packet,    raw},
-                  %%                       {reuseaddr, true},
-                  %%                       {backlog,   128},
-                  %%                       {nodelay,   true}]}
-                 ]},
+   %% TCP/Socket options (as per the broker configuration).
+   %% {tcp_listen_options, [binary,
+   %%                       {packet,    raw},
+   %%                       {reuseaddr, true},
+   %%                       {backlog,   128},
+   %%                       {nodelay,   true}]}
+  ]},
 
  %% ----------------------------------------------------------------------------
  %% RabbiMQ AMQP 1.0 Support
@@ -283,7 +285,7 @@
   [%% Set the default user.
    %% {default_user, "guest"},
 
-   %% Enable protocol strict mode.
+   %% Enable protocol strict mode. See the README for more information.
    %% {protocol_strict_mode, false}
   ]},
 
@@ -295,8 +297,9 @@
  %% ----------------------------------------------------------------------------
 
  {rabbitmq_auth_backend_ldap,
-  [%% Specify a list of LDAP Servers.
-   %% {servers, []},
+  [%% Specify server's to bind to. You *must* set this in order for the plugin
+   %% to work properly.
+   {servers, ["your-server-name-goes-here"]}
 
    %% Set user DN pattern.
    %% {user_dn_pattern, "cn=${username},ou=People,dc=example,dc=com"},
@@ -307,17 +310,19 @@
    %% Specify the LDAP port.
    %% {port, 389},
 
-   %% Enable logging.
+   %% Enable logging of LDAP queries.
    %% {log, false},
 
-   %% Set vhost access query.
+   %% Set the query to use when determining vhost access.
    %% {vhost_access_query, {in_group
    %%                        "ou=${vhost}-users,ou=vhosts,dc=example,dc=com"}},
 
-   %% Set resource access query.
+   %% Set the query to use when determining resource (e.g., queue) access.
    %% {resource_access_query, {constant, true}},
 
-   %% Set tag queries.
+   %% Set queries to determine which tags a user has.
+   %% See https://www.rabbitmq.com/management.html#permissions for a detailed
+   %% explanation of tags/permissions.
    %% {tag_queries, []}
   ]}
 ].