Improve a few description fields

modules/home-environment.nix

@@ -100,7 +100,9 @@ in
           options = {
             target = mkOption {
               type = types.str;
-              description = "Path to target file relative to $HOME.";
+              description = ''
+                Path to target file relative to <envar>HOME</envar>.
+              '';
             };
 
             text = mkOption {
@@ -147,6 +149,7 @@ in
     home.sessionVariables = mkOption {
       default = {};
       type = types.attrs;
+      example = { EDITOR = "emacs"; GS_OPTIONS = "-sPAPERSIZE=a4"; };
       description = "Environment variables to always set at login.";
     };
 

modules/programs/bash.nix

@@ -38,6 +38,7 @@ in
       historyIgnore = mkOption {
         type = types.listOf types.str;
         default = [];
+        example = [ "ls" "cd" "exit" ];
         description = "List of commands that should not be saved to the history list.";
       };
 

modules/programs/beets.nix

@@ -14,7 +14,10 @@ in
       settings = mkOption {
         type = types.attrs;
         default = {};
-        description = "Configuration written to ~/.config/beets/config.yaml";
+        description = ''
+          Configuration written to
+          <filename>~/.config/beets/config.yaml</filename>
+        '';
       };
     };
   };

modules/programs/git.nix

@@ -26,7 +26,7 @@ let
         gpgPath = mkOption {
           type = types.str;
           default = "${pkgs.gnupg}/bin/gpg2";
-          defaultText = "''${pkgs.gnupg}/bin/gpg2";
+          defaultText = "\${pkgs.gnupg}/bin/gpg2";
           description = "Path to GnuPG binary to use.";
         };
       };

modules/programs/gnome-terminal.nix

@@ -169,6 +169,7 @@ in
       profile = mkOption {
         default = {};
         type = types.loaOf profileSubModule;
+        description = "A set of Gnome Terminal profiles.";
       };
     };
   };

modules/xresources.nix

@@ -21,15 +21,14 @@ in
     xresources.properties = mkOption {
       type = types.nullOr types.attrs;
       default = null;
-      example = ''
-        {
-          "XTerm*faceName" = "dejavu sans mono";
-          "Emacs*toolBar" = 0;
-        }
-      '';
+      example = {
+        "XTerm*faceName" = "dejavu sans mono";
+        "Emacs*toolBar" = 0;
+      };
       description = ''
-        X server resources that should be set. If null, then this
-        feature is disabled and no ~/.Xresources link is produced.
+        X server resources that should be set. If <code>null</code>,
+        then this feature is disabled and no
+        <filename>~/.Xresources</filename> link is produced.
       '';
     };
   };