rabbitmq module: Update documentation

Elaborate on the two config file formats.

1 files changed, 23 insertions, 6 deletions

diff --git a/nixos/modules/services/amqp/rabbitmq.nix b/nixos/modules/services/amqp/rabbitmq.nix
index c6878dd67db..43998296a18 100644
--- a/nixos/modules/services/amqp/rabbitmq.nix
+++ b/nixos/modules/services/amqp/rabbitmq.nix
@@ -87,9 +87,19 @@ in {
           }
         '';
         description = ''
-          New style config options.
-
-          See http://www.rabbitmq.com/configure.html
+          Configuration options in RabbitMQ's new config file format,
+          which is a simple key-value format that can not express nested
+          data structures. This is known as the <literal>rabbitmq.conf</literal> file,
+          although outside NixOS that filename may have Erlang syntax, particularly
+          prior to RabbitMQ 3.7.0.
+
+          If you do need to express nested data structures, you can use
+          <literal>config</literal> option. Configuration from <literal>config</literal>
+          will be merged into the these options by RabbitMQ at runtime to
+          form the final configuration.
+
+          See http://www.rabbitmq.com/configure.html#config-items
+          For the distinct formats, see http://www.rabbitmq.com/configure.html#config-file-formats
         '';
       };
 
@@ -97,10 +107,17 @@ in {
         default = "";
         type = types.str;
         description = ''
-          Verbatim advanced configuration file contents.
-          Prefered way is to use configItems.
+          Verbatim advanced configuration file contents using the Erlang syntax.
+          This is also known as the <literal>advanced.config</literal> file or the old config format.
+
+          Where possible, the use <literal>configItems</literal> is preferred. However, nested
+          data structures can only be expressed properly using the <literal>config</literal> option.
+
+          The contents of this option will be merged into the <literal>configItems</literal>
+          by RabbitMQ at runtime to form the final configuration.
 
-          See http://www.rabbitmq.com/configure.html
+          See the second table on http://www.rabbitmq.com/configure.html#config-items
+          For the distinct formats, see http://www.rabbitmq.com/configure.html#config-file-formats
         '';
       };