From 55ef9612a24d53594f97c71ff38b9e46b0980c9c Mon Sep 17 00:00:00 2001
From: Maximilian Bosch <maximilian@mbosch.me>
Date: Sun, 6 Dec 2020 17:26:13 +0100
Subject: [PATCH] nixos/nginx: improve documentation for `config`

Unfortunately, I had a use-case where `services.nginx.config` was
necessary quite recently. While working on that config I had to look up
the module's code to understand which options can be used and which
don't.

To slightly improve the situation, I changed the documentation like
this:

* Added `types.str` as type since `config` is not mergeable on purpose.
  It must be a string as it's rendered verbatim into `nginx.conf` and if
  the type is `unspecified`, it can be confused with RFC42-like options.

* Mention which config options that don't generate config in
  `nginx.conf` are NOT mutually exclusive.
---
 .../services/web-servers/nginx/default.nix    | 23 ++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/nixos/modules/services/web-servers/nginx/default.nix b/nixos/modules/services/web-servers/nginx/default.nix
index e9630d379f3..62671e9d748 100644
--- a/nixos/modules/services/web-servers/nginx/default.nix
+++ b/nixos/modules/services/web-servers/nginx/default.nix
@@ -390,13 +390,24 @@ in
       };
 
       config = mkOption {
+        type = types.str;
         default = "";
-        description = "
-          Verbatim nginx.conf configuration.
-          This is mutually exclusive with the structured configuration
-          via virtualHosts and the recommendedXyzSettings configuration
-          options. See appendConfig for appending to the generated http block.
-        ";
+        description = ''
+          Verbatim <filename>nginx.conf</filename> configuration.
+          This is mutually exclusive to any other config option for
+          <filename>nginx.conf</filename> except for
+          <itemizedlist>
+          <listitem><para><xref linkend="opt-services.nginx.appendConfig" />
+          </para></listitem>
+          <listitem><para><xref linkend="opt-services.nginx.httpConfig" />
+          </para></listitem>
+          <listitem><para><xref linkend="opt-services.nginx.logError" />
+          </para></listitem>
+          </itemizedlist>
+
+          If additional verbatim config in addition to other options is needed,
+          <xref linkend="opt-services.nginx.appendConfig" /> should be used instead.
+        '';
       };
 
       appendConfig = mkOption {