rabbitmq module: Update documentation

Elaborate on the two config file formats.
NixOS · Sep 25, 2018 · 272fd84 · 272fd84
1 parent 7e3d35a
commit 272fd84
Showing 1 changed file with 23 additions and 6 deletions.
diff --git a/nixos/modules/services/amqp/rabbitmq.nix b/nixos/modules/services/amqp/rabbitmq.nix
@@ -87,20 +87,37 @@ 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
         '';
       };
 
       config = mkOption {
         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>configItems</literal> option.
+
+          The contents of this option will be merged by 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
         '';
       };