treewide: improve option descriptions

modules/environment/etc/default.nix

@@ -28,8 +28,8 @@ let
           type = types.bool;
           default = true;
           description = ''
-            Whether this /etc file should be generated.  This
+            Whether this <filename>/etc</filename> file should be generated.  This
-            option allows specific /etc files to be disabled.
+            option allows specific <filename>/etc</filename> files to be disabled.
           '';
         };
 

modules/environment/links.nix

@@ -1,4 +1,4 @@
-# Copyright (c) 2019-2020, see AUTHORS. Licensed under MIT License, see LICENSE.
+# Copyright (c) 2019-2022, see AUTHORS. Licensed under MIT License, see LICENSE.
 
 { config, lib, pkgs, ... }:
 
@@ -18,13 +18,13 @@ in
       binSh = mkOption {
         type = types.str;
         readOnly = true;
-        description = "Path to /bin/sh executable.";
+        description = "Path to <filename>/bin/sh</filename> executable.";
       };
 
       usrBinEnv = mkOption {
         type = types.str;
         readOnly = true;
-        description = "Path to /usr/bin/env executable.";
+        description = "Path to <filename>/usr/bin/env</filename> executable.";
       };
     };
 

modules/environment/login/default.nix

@@ -37,7 +37,7 @@ in
         type = types.package;
         readOnly = true;
         internal = true;
-        description = "proot-static package.";
+        description = "<literal>proot-static</literal> package.";
       };
     };
 

modules/environment/nix.nix

@@ -31,7 +31,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.nix;
-        defaultText = "pkgs.nix";
+        defaultText = literalExpression "pkgs.nix";
         description = ''
           This option specifies the Nix package instance to use throughout the system.
         '';
@@ -101,9 +101,7 @@ in
           }
         ));
         default = { };
-        description = ''
+        description = "A system-wide flake registry.";
-          A system-wide flake registry.
-        '';
       };
 
       substituters = mkOption {
@@ -128,7 +126,7 @@ in
       extraOptions = mkOption {
         type = types.lines;
         default = "";
-        description = "Extra config to be appended to /etc/nix/nix.conf.";
+        description = "Extra config to be appended to <filename>/etc/nix/nix.conf</filename>.";
       };
     };
 

modules/environment/session-init.nix

@@ -67,7 +67,9 @@ in
         example = { EDITOR = "emacs"; GS_OPTIONS = "-sPAPERSIZE=a4"; };
         description = ''
           Environment variables to always set at login.
+
           </para><para>
+
           The values may refer to other environment variables using
           POSIX.2 style variable references. For example, a variable
           <varname>parameter</varname> may be referenced as
@@ -76,19 +78,24 @@ in
           <code>''${parameter:-foo}</code> and, similarly, an alternate
           value <literal>bar</literal> can be given as per
           <code>''${parameter:+bar}</code>.
+
           </para><para>
+
           Note, these variables may be set in any order so no session
           variable may have a runtime dependency on another session
           variable. In particular code like
+
           <programlisting language="nix">
           environment.sessionVariables = {
             FOO = "Hello";
             BAR = "$FOO World!";
           };
           </programlisting>
+
           may not work as expected. If you need to reference another
           session variable, then do so inside Nix instead. The above
           example then becomes
+
           <programlisting language="nix">
           environment.sessionVariables = {
             FOO = "Hello";

modules/home-manager.nix

@@ -53,7 +53,10 @@ in
         default = null;
         # Prevent the entire submodule being included in the documentation.
         visible = "shallow";
-        description = "Home Manager configuration.";
+        description = ''
+          Home Manager configuration, see
+          <link xlink:href="https://nix-community.github.io/home-manager/options.html" />.
+        '';
       };
 
       extraSpecialArgs = mkOption {
@@ -67,14 +70,7 @@ in
       };
 
       sharedModules = mkOption {
-        type = with types;
+        type = with types; listOf raw;
-          # TODO: use types.raw once this PR is merged: https://github.com/NixOS/nixpkgs/pull/132448
-          listOf (mkOptionType {
-            name = "submodule";
-            inherit (submodule { }) check;
-            merge = lib.options.mergeOneOption;
-            description = "Home Manager modules";
-          });
         default = [ ];
         example = literalExpression "[ { home.packages = [ nixpkgs-fmt ]; } ]";
         description = ''

modules/nixpkgs/options.nix

@@ -117,8 +117,7 @@ in
 
       overlays = mkOption {
         default = null;
-        example = literalExpression
+        example = literalExpression ''
-          ''
           [ (self: super: {
               openssh = super.openssh.override {
                 hpnSupport = true;

modules/terminal.nix

@@ -20,8 +20,7 @@ in
       example = lib.literalExpression
         ''"''${pkgs.terminus_font_ttf}/share/fonts/truetype/TerminusTTF.ttf"'';
       description = ''
-        Font used for the terminal.
+        Font used for the terminal.  Must be a path to a TTF font.
-        Must be a path to a TTF font.
       '';
     };
 

modules/user.nix

@@ -50,6 +50,7 @@ in
       shell = mkOption {
         type = types.path;
         default = "${pkgs.bashInteractive}/bin/bash";
+        defaultText = literalExpression "${pkgs.bashInteractive}/bin/bash";
         description = "Path to login shell.";
       };
 

modules/version.nix

@@ -18,7 +18,9 @@ with lib;
         configuration defaults in a way that is incompatible with
         stateful data. This could, for example, include switching the
         default data format or location of a file.
+
         </para><para>
+
         The <emphasis>state version</emphasis> indicates which default
         settings are in effect and will therefore help avoid breaking
         program configurations. Switching to a higher state version