From b76fb0954ea679938f7972800571eb273f1f46c1 Mon Sep 17 00:00:00 2001 From: Tobias Happ Date: Wed, 26 Oct 2022 12:05:14 +0200 Subject: [PATCH] treewide: improve option descriptions --- modules/environment/etc/default.nix | 4 +-- modules/environment/links.nix | 6 ++-- modules/environment/login/default.nix | 2 +- modules/environment/nix.nix | 8 ++--- modules/environment/session-init.nix | 7 ++++ modules/home-manager.nix | 14 +++----- modules/nixpkgs/options.nix | 51 +++++++++++++-------------- modules/terminal.nix | 3 +- modules/user.nix | 1 + modules/version.nix | 2 ++ 10 files changed, 50 insertions(+), 48 deletions(-) diff --git a/modules/environment/etc/default.nix b/modules/environment/etc/default.nix index cdff35d..226ea7d 100644 --- a/modules/environment/etc/default.nix +++ b/modules/environment/etc/default.nix @@ -28,8 +28,8 @@ let type = types.bool; default = true; description = '' - Whether this /etc file should be generated. This - option allows specific /etc files to be disabled. + Whether this /etc file should be generated. This + option allows specific /etc files to be disabled. ''; }; diff --git a/modules/environment/links.nix b/modules/environment/links.nix index fb65f5f..7c80b53 100644 --- a/modules/environment/links.nix +++ b/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 /bin/sh executable."; }; usrBinEnv = mkOption { type = types.str; readOnly = true; - description = "Path to /usr/bin/env executable."; + description = "Path to /usr/bin/env executable."; }; }; diff --git a/modules/environment/login/default.nix b/modules/environment/login/default.nix index ceefc30..a89cf3f 100644 --- a/modules/environment/login/default.nix +++ b/modules/environment/login/default.nix @@ -37,7 +37,7 @@ in type = types.package; readOnly = true; internal = true; - description = "proot-static package."; + description = "proot-static package."; }; }; diff --git a/modules/environment/nix.nix b/modules/environment/nix.nix index 092eb2e..aee9e6e 100644 --- a/modules/environment/nix.nix +++ b/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 = '' - A system-wide flake registry. - ''; + description = "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 /etc/nix/nix.conf."; }; }; diff --git a/modules/environment/session-init.nix b/modules/environment/session-init.nix index 83366d3..ea86795 100644 --- a/modules/environment/session-init.nix +++ b/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. + + The values may refer to other environment variables using POSIX.2 style variable references. For example, a variable parameter may be referenced as @@ -76,19 +78,24 @@ in ''${parameter:-foo} and, similarly, an alternate value bar can be given as per ''${parameter:+bar}. + + 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 + environment.sessionVariables = { FOO = "Hello"; BAR = "$FOO World!"; }; + may not work as expected. If you need to reference another session variable, then do so inside Nix instead. The above example then becomes + environment.sessionVariables = { FOO = "Hello"; diff --git a/modules/home-manager.nix b/modules/home-manager.nix index 5ebc1ef..21d3f3b 100644 --- a/modules/home-manager.nix +++ b/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 + . + ''; }; extraSpecialArgs = mkOption { @@ -67,14 +70,7 @@ in }; sharedModules = mkOption { - type = with types; - # 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"; - }); + type = with types; listOf raw; default = [ ]; example = literalExpression "[ { home.packages = [ nixpkgs-fmt ]; } ]"; description = '' diff --git a/modules/nixpkgs/options.nix b/modules/nixpkgs/options.nix index 06178d6..f126c22 100644 --- a/modules/nixpkgs/options.nix +++ b/modules/nixpkgs/options.nix @@ -91,24 +91,24 @@ in you need to include something like - { pkgs, config, ...}: + { pkgs, config, ...}: - { - # for Nix-on-Droid - nixpkgs.config = import ./nixpkgs-config.nix; + { + # for Nix-on-Droid + nixpkgs.config = import ./nixpkgs-config.nix; - # for Home Manager - home-manager.config.nixpkgs.config = import ./nixpkgs-config.nix; - # -or- - home-manager.config = - { pkgs, ... }: - { - # for Home Manager - nixpkgs.config = import ./nixpkgs-config.nix; - # for commands like nix-env - xdg.configFile."nixpkgs/config.nix".source = ./nixpkgs-config.nix; - }; - } + # for Home Manager + home-manager.config.nixpkgs.config = import ./nixpkgs-config.nix; + # -or- + home-manager.config = + { pkgs, ... }: + { + # for Home Manager + nixpkgs.config = import ./nixpkgs-config.nix; + # for commands like nix-env + xdg.configFile."nixpkgs/config.nix".source = ./nixpkgs-config.nix; + }; + } in your Nix-on-Droid configuration. @@ -117,17 +117,16 @@ in overlays = mkOption { default = null; - example = literalExpression - '' - [ (self: super: { - openssh = super.openssh.override { - hpnSupport = true; - withKerberos = true; - kerberos = self.libkrb5; - }; + example = literalExpression '' + [ (self: super: { + openssh = super.openssh.override { + hpnSupport = true; + withKerberos = true; + kerberos = self.libkrb5; }; - ) ] - ''; + }; + ) ] + ''; type = types.nullOr (types.listOf overlayType); description = '' List of overlays to use with the Nix Packages collection. (For diff --git a/modules/terminal.nix b/modules/terminal.nix index c482dae..08e8636 100644 --- a/modules/terminal.nix +++ b/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. - Must be a path to a TTF font. + Font used for the terminal. Must be a path to a TTF font. ''; }; diff --git a/modules/user.nix b/modules/user.nix index d33d6af..6ed9f91 100644 --- a/modules/user.nix +++ b/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."; }; diff --git a/modules/version.nix b/modules/version.nix index 3fc4152..9aac3d2 100644 --- a/modules/version.nix +++ b/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. + + The state version indicates which default settings are in effect and will therefore help avoid breaking program configurations. Switching to a higher state version