diff --git a/nixos/modules/services/web-servers/nginx/default.nix b/nixos/modules/services/web-servers/nginx/default.nix
index 1978de6da6ee..b3889cb02946 100644
--- a/nixos/modules/services/web-servers/nginx/default.nix
+++ b/nixos/modules/services/web-servers/nginx/default.nix
@@ -235,7 +235,7 @@ in
       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.";
       };
 
@@ -246,9 +246,18 @@ in
         default = {
           localhost = {};
         };
-        example = [];
-        description = ''
+        example = literalExample ''
+          {
+            "hydra.example.com" = {
+              forceSSL = true;
+              enableACME = true;
+              locations."/" = {
+                proxyPass = "http://localhost:3000";
+              };
+            };
+          };
         '';
+        description = "Declarative vhost config";
       };
     };
   };
diff --git a/nixos/modules/services/web-servers/nginx/vhost-options.nix b/nixos/modules/services/web-servers/nginx/vhost-options.nix
index d684d7c1ff62..ee3f68bf8059 100644
--- a/nixos/modules/services/web-servers/nginx/vhost-options.nix
+++ b/nixos/modules/services/web-servers/nginx/vhost-options.nix
@@ -21,7 +21,7 @@ with lib;
       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).
       '';
     };
@@ -109,7 +109,17 @@ with lib;
     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 {
@@ -117,9 +127,14 @@ with lib;
         inherit lib;
       }));
       default = {};
-      example = {};
-      description = ''
+      example = literalExample ''
+        {
+          "/" = {
+            proxyPass = "http://localhost:3000";
+          };
+        };
       '';
+      description = "Declarative location config";
     };
   };
 }