nixos/*: automatically convert option descriptions

conversions were done using https://github.com/pennae/nix-doc-munge
using (probably) rev f34e145 running

    nix-doc-munge nixos/**/*.nix
    nix-doc-munge --import nixos/**/*.nix

the tool ensures that only changes that could affect the generated
manual *but don't* are committed, other changes require manual review
and are discarded.

2 files changed, 94 insertions, 94 deletions

diff --git a/nixos/lib/systemd-types.nix b/nixos/lib/systemd-types.nix
index 961b6d7f98514..a109f248b1704 100644
--- a/nixos/lib/systemd-types.nix
+++ b/nixos/lib/systemd-types.nix
@@ -37,11 +37,11 @@ rec {
 
   initrdContents = types.attrsOf (types.submodule ({ config, options, name, ... }: {
     options = {
-      enable = mkEnableOption "copying of this file and symlinking it" // { default = true; };
+      enable = mkEnableOption (lib.mdDoc "copying of this file and symlinking it") // { default = true; };
 
       target = mkOption {
         type = types.path;
-        description = ''
+        description = lib.mdDoc ''
           Path of the symlink.
         '';
         default = name;
@@ -50,12 +50,12 @@ rec {
       text = mkOption {
         default = null;
         type = types.nullOr types.lines;
-        description = "Text of the file.";
+        description = lib.mdDoc "Text of the file.";
       };
 
       source = mkOption {
         type = types.path;
-        description = "Path of the source file.";
+        description = lib.mdDoc "Path of the source file.";
       };
     };
 
diff --git a/nixos/lib/systemd-unit-options.nix b/nixos/lib/systemd-unit-options.nix
index ae4fa1a336287..c79fc88df1149 100644
--- a/nixos/lib/systemd-unit-options.nix
+++ b/nixos/lib/systemd-unit-options.nix
@@ -37,24 +37,24 @@ in rec {
     enable = mkOption {
       default = true;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         If set to false, this unit will be a symlink to
         /dev/null. This is primarily useful to prevent specific
         template instances
-        (e.g. <literal>serial-getty@ttyS0</literal>) from being
-        started. Note that <literal>enable=true</literal> does not
+        (e.g. `serial-getty@ttyS0`) from being
+        started. Note that `enable=true` does not
         make a unit start by default at boot; if you want that, see
-        <literal>wantedBy</literal>.
+        `wantedBy`.
       '';
     };
 
     requiredBy = mkOption {
       default = [];
       type = types.listOf unitNameType;
-      description = ''
+      description = lib.mdDoc ''
         Units that require (i.e. depend on and need to go down with)
-        this unit. The discussion under <literal>wantedBy</literal>
-        applies here as well: inverse <literal>.requires</literal>
+        this unit. The discussion under `wantedBy`
+        applies here as well: inverse `.requires`
         symlinks are established.
       '';
     };
@@ -62,16 +62,16 @@ in rec {
     wantedBy = mkOption {
       default = [];
       type = types.listOf unitNameType;
-      description = ''
+      description = lib.mdDoc ''
         Units that want (i.e. depend on) this unit. The standard way
         to make a unit start by default at boot is to set this option
-        to <literal>[ "multi-user.target" ]</literal>. That's despite
+        to `[ "multi-user.target" ]`. That's despite
         the fact that the systemd.unit(5) manpage says this option
-        goes in the <literal>[Install]</literal> section that controls
-        the behaviour of <literal>systemctl enable</literal>. Since
+        goes in the `[Install]` section that controls
+        the behaviour of `systemctl enable`. Since
         such a process is stateful and thus contrary to the design of
         NixOS, setting this option instead causes the equivalent
-        inverse <literal>.wants</literal> symlink to be present,
+        inverse `.wants` symlink to be present,
         establishing the same desired relationship in a stateless way.
       '';
     };
@@ -79,7 +79,7 @@ in rec {
     aliases = mkOption {
       default = [];
       type = types.listOf unitNameType;
-      description = "Aliases of that unit.";
+      description = lib.mdDoc "Aliases of that unit.";
     };
 
   };
@@ -89,7 +89,7 @@ in rec {
     text = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = "Text of this systemd unit.";
+      description = lib.mdDoc "Text of this systemd unit.";
     };
 
     unit = mkOption {
@@ -105,19 +105,19 @@ in rec {
       description = mkOption {
         default = "";
         type = types.singleLineStr;
-        description = "Description of this unit used in systemd messages and progress indicators.";
+        description = lib.mdDoc "Description of this unit used in systemd messages and progress indicators.";
       };
 
       documentation = mkOption {
         default = [];
         type = types.listOf types.str;
-        description = "A list of URIs referencing documentation for this unit or its configuration.";
+        description = lib.mdDoc "A list of URIs referencing documentation for this unit or its configuration.";
       };
 
       requires = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           Start the specified units when this unit is started, and stop
           this unit when the specified units are stopped or fail.
         '';
@@ -126,7 +126,7 @@ in rec {
       wants = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           Start the specified units when this unit is started.
         '';
       };
@@ -134,7 +134,7 @@ in rec {
       after = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           If the specified units are started at the same time as
           this unit, delay this unit until they have started.
         '';
@@ -143,7 +143,7 @@ in rec {
       before = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           If the specified units are started at the same time as
           this unit, delay them until this unit has started.
         '';
@@ -152,7 +152,7 @@ in rec {
       bindsTo = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           Like ‘requires’, but in addition, if the specified units
           unexpectedly disappear, this unit will be stopped as well.
         '';
@@ -161,7 +161,7 @@ in rec {
       partOf = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           If the specified units are stopped or restarted, then this
           unit is stopped or restarted as well.
         '';
@@ -170,7 +170,7 @@ in rec {
       conflicts = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           If the specified units are started, then this unit is stopped
           and vice versa.
         '';
@@ -179,7 +179,7 @@ in rec {
       requisite = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           Similar to requires. However if the units listed are not started,
           they will not be started and the transaction will fail.
         '';
@@ -189,17 +189,17 @@ in rec {
         default = {};
         example = { RequiresMountsFor = "/data"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Unit]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Unit]` section of the unit.  See
+          {manpage}`systemd.unit(5)` for details.
         '';
       };
 
       onFailure = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           A list of one or more units that are activated when
           this unit enters the "failed" state.
         '';
@@ -208,7 +208,7 @@ in rec {
       onSuccess = mkOption {
         default = [];
         type = types.listOf unitNameType;
-        description = ''
+        description = lib.mdDoc ''
           A list of one or more units that are activated when
           this unit enters the "inactive" state.
         '';
@@ -216,7 +216,7 @@ in rec {
 
       startLimitBurst = mkOption {
          type = types.int;
-         description = ''
+         description = lib.mdDoc ''
            Configure unit start rate limiting. Units which are started
            more than startLimitBurst times within an interval time
            interval are not permitted to start any more.
@@ -225,7 +225,7 @@ in rec {
 
       startLimitIntervalSec = mkOption {
          type = types.int;
-         description = ''
+         description = lib.mdDoc ''
            Configure unit start rate limiting. Units which are started
            more than startLimitBurst times within an interval time
            interval are not permitted to start any more.
@@ -244,7 +244,7 @@ in rec {
       restartTriggers = mkOption {
         default = [];
         type = types.listOf types.unspecified;
-        description = ''
+        description = lib.mdDoc ''
           An arbitrary list of items such as derivations.  If any item
           in the list changes between reconfigurations, the service will
           be restarted.
@@ -254,7 +254,7 @@ in rec {
       reloadTriggers = mkOption {
         default = [];
         type = types.listOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           An arbitrary list of items such as derivations.  If any item
           in the list changes between reconfigurations, the service will
           be reloaded.  If anything but a reload trigger changes in the
@@ -272,16 +272,16 @@ in rec {
         default = {};
         type = with types; attrsOf (nullOr (oneOf [ str path package ]));
         example = { PATH = "/foo/bar/bin"; LANG = "nl_NL.UTF-8"; };
-        description = "Environment variables passed to the service's processes.";
+        description = lib.mdDoc "Environment variables passed to the service's processes.";
       };
 
       path = mkOption {
         default = [];
         type = with types; listOf (oneOf [ package str ]);
-        description = ''
-          Packages added to the service's <envar>PATH</envar>
-          environment variable.  Both the <filename>bin</filename>
-          and <filename>sbin</filename> subdirectories of each
+        description = lib.mdDoc ''
+          Packages added to the service's {env}`PATH`
+          environment variable.  Both the {file}`bin`
+          and {file}`sbin` subdirectories of each
           package are added.
         '';
       };
@@ -292,29 +292,29 @@ in rec {
           { RestartSec = 5;
           };
         type = types.addCheck (types.attrsOf unitOption) checkService;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Service]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Service]` section of the unit.  See
+          {manpage}`systemd.service(5)` for details.
         '';
       };
 
       script = mkOption {
         type = types.lines;
         default = "";
-        description = "Shell commands executed as the service's main process.";
+        description = lib.mdDoc "Shell commands executed as the service's main process.";
       };
 
       scriptArgs = mkOption {
         type = types.str;
         default = "";
-        description = "Arguments passed to the main process script.";
+        description = lib.mdDoc "Arguments passed to the main process script.";
       };
 
       preStart = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Shell commands executed before the service's main process
           is started.
         '';
@@ -323,7 +323,7 @@ in rec {
       postStart = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Shell commands executed after the service's main process
           is started.
         '';
@@ -332,7 +332,7 @@ in rec {
       reload = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Shell commands executed when the service's main process
           is reloaded.
         '';
@@ -341,7 +341,7 @@ in rec {
       preStop = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Shell commands executed to stop the service.
         '';
       };
@@ -349,7 +349,7 @@ in rec {
       postStop = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Shell commands executed after the service's main process
           has exited.
         '';
@@ -403,7 +403,7 @@ in rec {
       restartIfChanged = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether the service should be restarted during a NixOS
           configuration switch if its definition has changed.
         '';
@@ -412,14 +412,14 @@ in rec {
       reloadIfChanged = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether the service should be reloaded during a NixOS
           configuration switch if its definition has changed.  If
-          enabled, the value of <option>restartIfChanged</option> is
+          enabled, the value of {option}`restartIfChanged` is
           ignored.
 
           This option should not be used anymore in favor of
-          <option>reloadTriggers</option> which allows more granular
+          {option}`reloadTriggers` which allows more granular
           control of when a service is reloaded and when a service
           is restarted.
         '';
@@ -428,14 +428,14 @@ in rec {
       stopIfChanged = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           If set, a changed unit is restarted by calling
-          <command>systemctl stop</command> in the old configuration,
-          then <command>systemctl start</command> in the new one.
+          {command}`systemctl stop` in the old configuration,
+          then {command}`systemctl start` in the new one.
           Otherwise, it is restarted in a single step using
-          <command>systemctl restart</command> in the new configuration.
+          {command}`systemctl restart` in the new configuration.
           The latter is less correct because it runs the
-          <literal>ExecStop</literal> commands from the new
+          `ExecStop` commands from the new
           configuration.
         '';
       };
@@ -444,12 +444,12 @@ in rec {
         type = with types; either str (listOf str);
         default = [];
         example = "Sun 14:00:00";
-        description = ''
+        description = lib.mdDoc ''
           Automatically start this unit at the given date/time, which
           must be in the format described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.  This is equivalent
+          {manpage}`systemd.time(7)`.  This is equivalent
           to adding a corresponding timer unit with
-          <option>OnCalendar</option> set to the value given here.
+          {option}`OnCalendar` set to the value given here.
         '';
         apply = v: if isList v then v else [ v ];
       };
@@ -471,9 +471,9 @@ in rec {
         default = [];
         type = types.listOf types.str;
         example = [ "0.0.0.0:993" "/run/my-socket" ];
-        description = ''
-          For each item in this list, a <literal>ListenStream</literal>
-          option in the <literal>[Socket]</literal> section will be created.
+        description = lib.mdDoc ''
+          For each item in this list, a `ListenStream`
+          option in the `[Socket]` section will be created.
         '';
       };
 
@@ -481,9 +481,9 @@ in rec {
         default = [];
         type = types.listOf types.str;
         example = [ "0.0.0.0:993" "/run/my-socket" ];
-        description = ''
-          For each item in this list, a <literal>ListenDatagram</literal>
-          option in the <literal>[Socket]</literal> section will be created.
+        description = lib.mdDoc ''
+          For each item in this list, a `ListenDatagram`
+          option in the `[Socket]` section will be created.
         '';
       };
 
@@ -491,10 +491,10 @@ in rec {
         default = {};
         example = { ListenStream = "/run/my-socket"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Socket]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Socket]` section of the unit.  See
+          {manpage}`systemd.socket(5)` for details.
         '';
       };
     };
@@ -523,11 +523,11 @@ in rec {
         default = {};
         example = { OnCalendar = "Sun 14:00:00"; Unit = "foo.service"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Timer]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details.
+          `[Timer]` section of the unit.  See
+          {manpage}`systemd.timer(5)` and
+          {manpage}`systemd.time(7)` for details.
         '';
       };
 
@@ -556,10 +556,10 @@ in rec {
         default = {};
         example = { PathChanged = "/some/path"; Unit = "changedpath.service"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Path]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Path]` section of the unit.  See
+          {manpage}`systemd.path(5)` for details.
         '';
       };
 
@@ -587,13 +587,13 @@ in rec {
       what = mkOption {
         example = "/dev/sda1";
         type = types.str;
-        description = "Absolute path of device node, file or other resource. (Mandatory)";
+        description = lib.mdDoc "Absolute path of device node, file or other resource. (Mandatory)";
       };
 
       where = mkOption {
         example = "/mnt";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Absolute path of a directory of the mount point.
           Will be created if it doesn't exist. (Mandatory)
         '';
@@ -603,24 +603,24 @@ in rec {
         default = "";
         example = "ext4";
         type = types.str;
-        description = "File system type.";
+        description = lib.mdDoc "File system type.";
       };
 
       options = mkOption {
         default = "";
         example = "noatime";
         type = types.commas;
-        description = "Options used to mount the file system.";
+        description = lib.mdDoc "Options used to mount the file system.";
       };
 
       mountConfig = mkOption {
         default = {};
         example = { DirectoryMode = "0775"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Mount]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Mount]` section of the unit.  See
+          {manpage}`systemd.mount(5)` for details.
         '';
       };
 
@@ -647,7 +647,7 @@ in rec {
       where = mkOption {
         example = "/mnt";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Absolute path of a directory of the mount point.
           Will be created if it doesn't exist. (Mandatory)
         '';
@@ -657,10 +657,10 @@ in rec {
         default = {};
         example = { DirectoryMode = "0775"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Automount]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Automount]` section of the unit.  See
+          {manpage}`systemd.automount(5)` for details.
         '';
       };
 
@@ -688,10 +688,10 @@ in rec {
         default = {};
         example = { MemoryMax = "2G"; };
         type = types.attrsOf unitOption;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Slice]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Slice]` section of the unit.  See
+          {manpage}`systemd.slice(5)` for details.
         '';
       };