nginx module: improve documentation

nixos/modules/services/web-servers/nginx/default.nix

···
       sslDhparam = mkOption {
         type = types.nullOr types.path;
         default = null;
-        example = literalExample "/path/to/dhparams.pem";
+        example = "/path/to/dhparams.pem";
         description = "Path to DH parameters file.";
       };
 
···
         default = {
           localhost = {};
         };
-        example = [];
-        description = ''
+        example = literalExample ''
+          {
+            "hydra.example.com" = {
+              forceSSL = true;
+              enableACME = true;
+              locations."/" = {
+                proxyPass = "http://localhost:3000";
+              };
+            };
+          };
         '';
+        description = "Declarative vhost config";
       };
     };
   };

nixos/modules/services/web-servers/nginx/vhost-options.nix

···
       type = types.nullOr types.int;
       default = null;
       description = ''
-        Port for the server. 80 for http
+        Port for the server. Defaults to 80 for http
         and 443 for https (i.e. when enableSSL is set).
       '';
     };
···
     basicAuth = mkOption {
       type = types.attrsOf types.str;
       default = {};
-      description = "user = password";
+      example = literalExample ''
+        {
+          user = "password";
+        };
+      '';
+      description = ''
+        Basic Auth protection for a vhost.
+
+        WARNING: This is implemented to store the password in plain text in the
+        nix store.
+      '';
     };
 
     locations = mkOption {
···
         inherit lib;
       }));
       default = {};
-      example = {};
-      description = ''
+      example = literalExample ''
+        {
+          "/" = {
+            proxyPass = "http://localhost:3000";
+          };
+        };
       '';
+      description = "Declarative location config";
     };
   };
 }