nixos/doc: clean up defaults and examples

19 files changed, 45 insertions, 49 deletions

diff --git a/nixos/modules/services/databases/aerospike.nix b/nixos/modules/services/databases/aerospike.nix
index 4b905f90529..8109762aea7 100644
--- a/nixos/modules/services/databases/aerospike.nix
+++ b/nixos/modules/services/databases/aerospike.nix
@@ -43,7 +43,7 @@ in
 
       package = mkOption {
         default = pkgs.aerospike;
-        defaultText = "pkgs.aerospike";
+        defaultText = literalExpression "pkgs.aerospike";
         type = types.package;
         description = "Which Aerospike derivation to use";
       };
diff --git a/nixos/modules/services/databases/cassandra.nix b/nixos/modules/services/databases/cassandra.nix
index 820be5085de..b36cac35e7c 100644
--- a/nixos/modules/services/databases/cassandra.nix
+++ b/nixos/modules/services/databases/cassandra.nix
@@ -4,7 +4,8 @@ let
   inherit (lib)
     concatStringsSep
     flip
-    literalExample
+    literalDocBook
+    literalExpression
     optionalAttrs
     optionals
     recursiveUpdate
@@ -136,8 +137,8 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.cassandra;
-      defaultText = "pkgs.cassandra";
-      example = literalExample "pkgs.cassandra_3_11";
+      defaultText = literalExpression "pkgs.cassandra";
+      example = literalExpression "pkgs.cassandra_3_11";
       description = ''
         The Apache Cassandra package to use.
       '';
@@ -276,7 +277,7 @@ in
     extraEnvSh = mkOption {
       type = types.lines;
       default = "";
-      example = "CLASSPATH=$CLASSPATH:\${extraJar}";
+      example = literalExpression ''"CLASSPATH=$CLASSPATH:''${extraJar}"'';
       description = ''
         Extra shell lines to be appended onto cassandra-env.sh.
       '';
@@ -436,6 +437,7 @@ in
         if versionAtLeast cfg.package.version "3.11"
         then pkgs.writeText "jmx-roles-file" defaultJmxRolesFile
         else null;
+      defaultText = literalDocBook ''generated configuration file if version is at least 3.11, otherwise <literal>null</literal>'';
       example = "/var/lib/cassandra/jmx.password";
       description = ''
         Specify your own jmx roles file.
diff --git a/nixos/modules/services/databases/cockroachdb.nix b/nixos/modules/services/databases/cockroachdb.nix
index 35fb46d69d8..eb061af9262 100644
--- a/nixos/modules/services/databases/cockroachdb.nix
+++ b/nixos/modules/services/databases/cockroachdb.nix
@@ -150,7 +150,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.cockroachdb;
-        defaultText = "pkgs.cockroachdb";
+        defaultText = literalExpression "pkgs.cockroachdb";
         description = ''
           The CockroachDB derivation to use for running the service.
 
diff --git a/nixos/modules/services/databases/couchdb.nix b/nixos/modules/services/databases/couchdb.nix
index 6cc29cd717e..16dd64f2373 100644
--- a/nixos/modules/services/databases/couchdb.nix
+++ b/nixos/modules/services/databases/couchdb.nix
@@ -44,8 +44,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.couchdb;
-        defaultText = "pkgs.couchdb";
-        example = literalExample "pkgs.couchdb";
+        defaultText = literalExpression "pkgs.couchdb";
         description = ''
           CouchDB package to use.
         '';
diff --git a/nixos/modules/services/databases/firebird.nix b/nixos/modules/services/databases/firebird.nix
index 0815487d4a1..4e3130bea22 100644
--- a/nixos/modules/services/databases/firebird.nix
+++ b/nixos/modules/services/databases/firebird.nix
@@ -44,11 +44,9 @@ in
 
       package = mkOption {
         default = pkgs.firebird;
-        defaultText = "pkgs.firebird";
+        defaultText = literalExpression "pkgs.firebird";
         type = types.package;
-        example = ''
-          <code>package = pkgs.firebird_3;</code>
-        '';
+        example = literalExpression "pkgs.firebird_3";
         description = ''
           Which Firebird package to be installed: <code>pkgs.firebird_3</code>
           For SuperServer use override: <code>pkgs.firebird_3.override { superServer = true; };</code>
@@ -56,7 +54,7 @@ in
       };
 
       port = mkOption {
-        default = "3050";
+        default = 3050;
         type = types.port;
         description = ''
           Port Firebird uses.
diff --git a/nixos/modules/services/databases/hbase.nix b/nixos/modules/services/databases/hbase.nix
index 2d1a47bbaa3..9132b7ed356 100644
--- a/nixos/modules/services/databases/hbase.nix
+++ b/nixos/modules/services/databases/hbase.nix
@@ -44,8 +44,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.hbase;
-        defaultText = "pkgs.hbase";
-        example = literalExample "pkgs.hbase";
+        defaultText = literalExpression "pkgs.hbase";
         description = ''
           HBase package to use.
         '';
diff --git a/nixos/modules/services/databases/influxdb.nix b/nixos/modules/services/databases/influxdb.nix
index 3b8c00929ba..c7c9871cfec 100644
--- a/nixos/modules/services/databases/influxdb.nix
+++ b/nixos/modules/services/databases/influxdb.nix
@@ -121,7 +121,7 @@ in
 
       package = mkOption {
         default = pkgs.influxdb;
-        defaultText = "pkgs.influxdb";
+        defaultText = literalExpression "pkgs.influxdb";
         description = "Which influxdb derivation to use";
         type = types.package;
       };
diff --git a/nixos/modules/services/databases/influxdb2.nix b/nixos/modules/services/databases/influxdb2.nix
index df7bac4261b..01b9c493484 100644
--- a/nixos/modules/services/databases/influxdb2.nix
+++ b/nixos/modules/services/databases/influxdb2.nix
@@ -11,7 +11,7 @@ in
       enable = mkEnableOption "the influxdb2 server";
       package = mkOption {
         default = pkgs.influxdb2;
-        defaultText = "pkgs.influxdb2";
+        defaultText = literalExpression "pkgs.influxdb2";
         description = "influxdb2 derivation to use.";
         type = types.package;
       };
diff --git a/nixos/modules/services/databases/monetdb.nix b/nixos/modules/services/databases/monetdb.nix
index 5c66fc7b2e3..52a2ef041f8 100644
--- a/nixos/modules/services/databases/monetdb.nix
+++ b/nixos/modules/services/databases/monetdb.nix
@@ -17,7 +17,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.monetdb;
-        defaultText = "pkgs.monetdb";
+        defaultText = literalExpression "pkgs.monetdb";
         description = "MonetDB package to use.";
       };
 
diff --git a/nixos/modules/services/databases/mongodb.nix b/nixos/modules/services/databases/mongodb.nix
index 5121e0415db..fccf85d482e 100644
--- a/nixos/modules/services/databases/mongodb.nix
+++ b/nixos/modules/services/databases/mongodb.nix
@@ -33,7 +33,7 @@ in
 
       package = mkOption {
         default = pkgs.mongodb;
-        defaultText = "pkgs.mongodb";
+        defaultText = literalExpression "pkgs.mongodb";
         type = types.package;
         description = "
           Which MongoDB derivation to use.
diff --git a/nixos/modules/services/databases/mysql.nix b/nixos/modules/services/databases/mysql.nix
index b801b5cce63..a9d9a6d8058 100644
--- a/nixos/modules/services/databases/mysql.nix
+++ b/nixos/modules/services/databases/mysql.nix
@@ -34,7 +34,7 @@ in
 
       package = mkOption {
         type = types.package;
-        example = literalExample "pkgs.mariadb";
+        example = literalExpression "pkgs.mariadb";
         description = "
           Which MySQL derivation to use. MariaDB packages are supported too.
         ";
@@ -43,7 +43,7 @@ in
       bind = mkOption {
         type = types.nullOr types.str;
         default = null;
-        example = literalExample "0.0.0.0";
+        example = "0.0.0.0";
         description = "Address to bind to. The default is to bind to all addresses.";
       };
 
@@ -74,12 +74,12 @@ in
       configFile = mkOption {
         type = types.path;
         default = settingsFile;
-        defaultText = "settingsFile";
+        defaultText = literalExpression "settingsFile";
         description = ''
           Override the configuration file used by MySQL. By default,
           NixOS generates one automatically from <option>services.mysql.settings</option>.
         '';
-        example = literalExample ''
+        example = literalExpression ''
           pkgs.writeText "my.cnf" '''
             [mysqld]
             datadir = /var/lib/mysql
@@ -109,7 +109,7 @@ in
             </para>
           </note>
         '';
-        example = literalExample ''
+        example = literalExpression ''
           {
             mysqld = {
               key_buffer_size = "6G";
@@ -167,7 +167,7 @@ in
           of MySQL. The schema attribute is optional: If not specified, an empty database is created.
         '';
         example = [
-          { name = "foodatabase"; schema = literalExample "./foodatabase.sql"; }
+          { name = "foodatabase"; schema = literalExpression "./foodatabase.sql"; }
           { name = "bardatabase"; }
         ];
       };
@@ -217,7 +217,7 @@ in
                 <link xlink:href="https://mariadb.com/kb/en/library/grant/">GRANT syntax</link>.
                 The attributes are used as <code>GRANT ''${attrName} ON ''${attrValue}</code>.
               '';
-              example = literalExample ''
+              example = literalExpression ''
                 {
                   "database.*" = "ALL PRIVILEGES";
                   "*.*" = "SELECT, LOCK TABLES";
@@ -235,7 +235,7 @@ in
           option is changed. This means that users created and permissions assigned once through this option or
           otherwise have to be removed manually.
         '';
-        example = literalExample ''
+        example = literalExpression ''
           [
             {
               name = "nextcloud";
diff --git a/nixos/modules/services/databases/neo4j.nix b/nixos/modules/services/databases/neo4j.nix
index 2a30923538d..f37e5ad1693 100644
--- a/nixos/modules/services/databases/neo4j.nix
+++ b/nixos/modules/services/databases/neo4j.nix
@@ -179,7 +179,7 @@ in {
     package = mkOption {
       type = types.package;
       default = pkgs.neo4j;
-      defaultText = "pkgs.neo4j";
+      defaultText = literalExpression "pkgs.neo4j";
       description = ''
         Neo4j package to use.
       '';
diff --git a/nixos/modules/services/databases/openldap.nix b/nixos/modules/services/databases/openldap.nix
index f0efc659cff..2c1e25d4308 100644
--- a/nixos/modules/services/databases/openldap.nix
+++ b/nixos/modules/services/databases/openldap.nix
@@ -34,7 +34,7 @@ let
           in types.attrsOf (types.submodule { options = hiddenOptions; });
           default = {};
           description = "Child entries of the current entry, with recursively the same structure.";
-          example = lib.literalExample ''
+          example = lib.literalExpression ''
             {
                 "cn=schema" = {
                 # The attribute used in the DN must be defined
@@ -127,6 +127,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.openldap;
+        defaultText = literalExpression "pkgs.openldap";
         description = ''
           OpenLDAP package to use.
 
@@ -158,14 +159,14 @@ in {
       settings = mkOption {
         type = ldapAttrsType;
         description = "Configuration for OpenLDAP, in OLC format";
-        example = lib.literalExample ''
+        example = lib.literalExpression ''
           {
             attrs.olcLogLevel = [ "stats" ];
             children = {
               "cn=schema".includes = [
-                 "\${pkgs.openldap}/etc/schema/core.ldif"
-                 "\${pkgs.openldap}/etc/schema/cosine.ldif"
-                 "\${pkgs.openldap}/etc/schema/inetorgperson.ldif"
+                 "''${pkgs.openldap}/etc/schema/core.ldif"
+                 "''${pkgs.openldap}/etc/schema/cosine.ldif"
+                 "''${pkgs.openldap}/etc/schema/inetorgperson.ldif"
               ];
               "olcDatabase={-1}frontend" = {
                 attrs = {
@@ -225,7 +226,7 @@ in {
           rebuilt on each server startup, so this will slow down server startup,
           especially with large databases.
         '';
-        example = lib.literalExample ''
+        example = lib.literalExpression ''
           {
             "dc=example,dc=org" = '''
               dn= dn: dc=example,dc=org
diff --git a/nixos/modules/services/databases/opentsdb.nix b/nixos/modules/services/databases/opentsdb.nix
index c4bd71f3d60..e873b2f7011 100644
--- a/nixos/modules/services/databases/opentsdb.nix
+++ b/nixos/modules/services/databases/opentsdb.nix
@@ -26,8 +26,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.opentsdb;
-        defaultText = "pkgs.opentsdb";
-        example = literalExample "pkgs.opentsdb";
+        defaultText = literalExpression "pkgs.opentsdb";
         description = ''
           OpenTSDB package to use.
         '';
diff --git a/nixos/modules/services/databases/pgmanage.nix b/nixos/modules/services/databases/pgmanage.nix
index 8508e76b5cd..f30f71866af 100644
--- a/nixos/modules/services/databases/pgmanage.nix
+++ b/nixos/modules/services/databases/pgmanage.nix
@@ -49,7 +49,7 @@ in {
     package = mkOption {
       type = types.package;
       default = pkgs.pgmanage;
-      defaultText = "pkgs.pgmanage";
+      defaultText = literalExpression "pkgs.pgmanage";
       description = ''
         The pgmanage package to use.
       '';
diff --git a/nixos/modules/services/databases/postgresql.nix b/nixos/modules/services/databases/postgresql.nix
index fd4a195787f..d49cb4c51a7 100644
--- a/nixos/modules/services/databases/postgresql.nix
+++ b/nixos/modules/services/databases/postgresql.nix
@@ -44,7 +44,7 @@ in
 
       package = mkOption {
         type = types.package;
-        example = literalExample "pkgs.postgresql_11";
+        example = literalExpression "pkgs.postgresql_11";
         description = ''
           PostgreSQL package to use.
         '';
@@ -66,7 +66,7 @@ in
 
       dataDir = mkOption {
         type = types.path;
-        defaultText = "/var/lib/postgresql/\${config.services.postgresql.package.psqlSchema}";
+        defaultText = literalExpression ''"/var/lib/postgresql/''${config.services.postgresql.package.psqlSchema}"'';
         example = "/var/lib/postgresql/11";
         description = ''
           The data directory for PostgreSQL. If left as the default value
@@ -161,7 +161,7 @@ in
                 <link xlink:href="https://www.postgresql.org/docs/current/sql-grant.html">GRANT syntax</link>.
                 The attributes are used as <code>GRANT ''${attrValue} ON ''${attrName}</code>.
               '';
-              example = literalExample ''
+              example = literalExpression ''
                 {
                   "DATABASE \"nextcloud\"" = "ALL PRIVILEGES";
                   "ALL TABLES IN SCHEMA public" = "ALL PRIVILEGES";
@@ -179,7 +179,7 @@ in
           option is changed. This means that users created and permissions assigned once through this option or
           otherwise have to be removed manually.
         '';
-        example = literalExample ''
+        example = literalExpression ''
           [
             {
               name = "nextcloud";
@@ -221,7 +221,7 @@ in
       extraPlugins = mkOption {
         type = types.listOf types.path;
         default = [];
-        example = literalExample "with pkgs.postgresql_11.pkgs; [ postgis pg_repack ]";
+        example = literalExpression "with pkgs.postgresql_11.pkgs; [ postgis pg_repack ]";
         description = ''
           List of PostgreSQL plugins. PostgreSQL version for each plugin should
           match version for <literal>services.postgresql.package</literal> value.
@@ -241,7 +241,7 @@ in
             escaped with two single quotes as described by the upstream documentation linked above.
           </para></note>
         '';
-        example = literalExample ''
+        example = literalExpression ''
           {
             log_connections = true;
             log_statement = "all";
diff --git a/nixos/modules/services/databases/redis.nix b/nixos/modules/services/databases/redis.nix
index 1b9358c81a1..578d9d9ec8d 100644
--- a/nixos/modules/services/databases/redis.nix
+++ b/nixos/modules/services/databases/redis.nix
@@ -47,7 +47,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.redis;
-        defaultText = "pkgs.redis";
+        defaultText = literalExpression "pkgs.redis";
         description = "Which Redis derivation to use.";
       };
 
@@ -133,7 +133,6 @@ in {
         type = with types; listOf (listOf int);
         default = [ [900 1] [300 10] [60 10000] ];
         description = "The schedule in which data is persisted to disk, represented as a list of lists where the first element represent the amount of seconds and the second the number of changes.";
-        example = [ [900 1] [300 10] [60 10000] ];
       };
 
       slaveOf = mkOption {
@@ -217,7 +216,7 @@ in {
           <link xlink:href="https://redis.io/topics/config"/>
           for details on supported values.
         '';
-        example = literalExample ''
+        example = literalExpression ''
           {
             loadmodule = [ "/path/to/my_module.so" "/path/to/other_module.so" ];
           }
diff --git a/nixos/modules/services/databases/riak.nix b/nixos/modules/services/databases/riak.nix
index 657eeea87bf..cc4237d038c 100644
--- a/nixos/modules/services/databases/riak.nix
+++ b/nixos/modules/services/databases/riak.nix
@@ -21,8 +21,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.riak;
-        defaultText = "pkgs.riak";
-        example = literalExample "pkgs.riak";
+        defaultText = literalExpression "pkgs.riak";
         description = ''
           Riak package to use.
         '';
diff --git a/nixos/modules/services/databases/victoriametrics.nix b/nixos/modules/services/databases/victoriametrics.nix
index 9e2c79e61a3..0513dcff172 100644
--- a/nixos/modules/services/databases/victoriametrics.nix
+++ b/nixos/modules/services/databases/victoriametrics.nix
@@ -6,7 +6,7 @@ let cfg = config.services.victoriametrics; in
     package = mkOption {
       type = types.package;
       default = pkgs.victoriametrics;
-      defaultText = "pkgs.victoriametrics";
+      defaultText = literalExpression "pkgs.victoriametrics";
       description = ''
         The VictoriaMetrics distribution to use.
       '';