From 7a2d065ccec902c17db71bd2ba3e485a0952f43b Mon Sep 17 00:00:00 2001 From: Gaetan Lepage Date: Sun, 9 Jun 2024 23:04:27 +0200 Subject: [PATCH] misc: ensure all options have a description --- modules/filetype.nix | 15 ++++++- modules/keymaps.nix | 1 + .../cmp/options/settings-options.nix | 4 ++ plugins/git/gitsigns/options.nix | 14 +++++- plugins/languages/treesitter/treesitter.nix | 1 + plugins/lsp/language-servers/_mk-lsp.nix | 7 +++ plugins/snippets/luasnip/default.nix | 27 ++++++----- plugins/statuslines/lightline.nix | 2 + plugins/telescope/default.nix | 5 ++- plugins/utils/hydra/hydras-option.nix | 4 ++ plugins/utils/nix-develop.nix | 17 ++++++- plugins/utils/nvim-colorizer.nix | 28 +++++++----- plugins/utils/which-key.nix | 45 +++++++++++++------ 13 files changed, 127 insertions(+), 43 deletions(-) diff --git a/modules/filetype.nix b/modules/filetype.nix index 0f1f132d..c9c715c2 100644 --- a/modules/filetype.nix +++ b/modules/filetype.nix @@ -17,7 +17,20 @@ let (listOf ( either str (submodule { options = { - priority = mkOption { type = int; }; + priority = mkOption { + type = ints.unsigned; + description = '' + Filename patterns can specify an optional priority to resolve cases when a file path + matches multiple patterns. + + Higher priorities are matched first. + When omitted, the priority defaults to 0. + + A pattern can contain environment variables of the form `"''${SOME_VAR}"` that will + be automatically expanded. + If the environment variable is not set, the pattern won't be matched. + ''; + }; }; }) )) diff --git a/modules/keymaps.nix b/modules/keymaps.nix index f1473950..e5177667 100644 --- a/modules/keymaps.nix +++ b/modules/keymaps.nix @@ -11,6 +11,7 @@ with lib; keymaps = mkOption { type = types.listOf helpers.keymaps.mapOptionSubmodule; default = [ ]; + description = "Nixvim keymaps."; example = [ { key = ""; diff --git a/plugins/completion/cmp/options/settings-options.nix b/plugins/completion/cmp/options/settings-options.nix index 1a258b46..1f78d191 100644 --- a/plugins/completion/cmp/options/settings-options.nix +++ b/plugins/completion/cmp/options/settings-options.nix @@ -39,6 +39,10 @@ with lib; mapping = mkOption { default = { }; type = with helpers.nixvimTypes; maybeRaw (attrsOf strLua); + description = '' + cmp mappings declaration. + See `:h cmp-mapping` for more information. + ''; apply = v: # Handle the raw case first diff --git a/plugins/git/gitsigns/options.nix b/plugins/git/gitsigns/options.nix index 5f356fea..4c016885 100644 --- a/plugins/git/gitsigns/options.nix +++ b/plugins/git/gitsigns/options.nix @@ -69,9 +69,19 @@ with lib; worktreeType = types.submodule { freeformType = with types; attrsOf anything; options = { - toplevel = mkOption { type = with helpers.nixvimTypes; maybeRaw str; }; + toplevel = mkOption { + type = with helpers.nixvimTypes; maybeRaw str; + description = '' + Path to the top-level of the parent git repository. + ''; + }; - gitdir = mkOption { type = with helpers.nixvimTypes; maybeRaw str; }; + gitdir = mkOption { + type = with helpers.nixvimTypes; maybeRaw str; + description = '' + Path to the git directory of the parent git repository (typically the `.git/` directory). + ''; + }; }; }; in diff --git a/plugins/languages/treesitter/treesitter.nix b/plugins/languages/treesitter/treesitter.nix index 2be9366d..81b9f14d 100644 --- a/plugins/languages/treesitter/treesitter.nix +++ b/plugins/languages/treesitter/treesitter.nix @@ -80,6 +80,7 @@ in mkOption { type = types.str; inherit default; + description = "Key shortcut"; }; in { diff --git a/plugins/lsp/language-servers/_mk-lsp.nix b/plugins/lsp/language-servers/_mk-lsp.nix index c3860beb..ba07d4c2 100644 --- a/plugins/lsp/language-servers/_mk-lsp.nix +++ b/plugins/lsp/language-servers/_mk-lsp.nix @@ -55,6 +55,13 @@ in cmd = mkOption { type = with types; nullOr (listOf str); default = if (cfg.package or null) != null then cmd cfg else null; + description = '' + A list where each entry corresponds to the blankspace delimited part of the command that + launches the server. + + The first entry is the binary used to run the language server. + Additional entries are passed as arguments. + ''; }; filetypes = helpers.mkNullOrOption (types.listOf types.str) '' diff --git a/plugins/snippets/luasnip/default.nix b/plugins/snippets/luasnip/default.nix index c3c4c084..fb33cdfb 100644 --- a/plugins/snippets/luasnip/default.nix +++ b/plugins/snippets/luasnip/default.nix @@ -71,18 +71,23 @@ in fromVscode = mkOption { default = [ ]; - example = '' + example = literalExpression '' [ - {} - { - paths = ./path/to/snippets; - } - ] - # generates: - # - # require("luasnip.loaders.from_vscode").lazy_load({}) - # require("luasnip.loaders.from_vscode").lazy_load({['paths'] = {'/nix/store/.../path/to/snippets'}}) - # + { } + { paths = ./path/to/snippets; } + ]''; + description = '' + List of custom vscode style snippets to load. + + For example, + ```nix + [ {} { paths = ./path/to/snippets; } ] + ``` + will generate the following lua: + ```lua + require("luasnip.loaders.from_vscode").lazy_load({}) + require("luasnip.loaders.from_vscode").lazy_load({['paths'] = {'/nix/store/.../path/to/snippets'}}) + ``` ''; type = types.listOf loaderSubmodule; }; diff --git a/plugins/statuslines/lightline.nix b/plugins/statuslines/lightline.nix index d86aa8bd..4e66db72 100644 --- a/plugins/statuslines/lightline.nix +++ b/plugins/statuslines/lightline.nix @@ -55,6 +55,7 @@ in active = mkOption { default = null; + description = "List of components for the active window."; type = types.nullOr ( types.submodule { options = @@ -72,6 +73,7 @@ in inactive = mkOption { default = null; + description = "List of components for inactive windows."; type = types.nullOr ( types.submodule { options = diff --git a/plugins/telescope/default.nix b/plugins/telescope/default.nix index 760b3b05..f0322c63 100644 --- a/plugins/telescope/default.nix +++ b/plugins/telescope/default.nix @@ -41,7 +41,10 @@ helpers.neovim-plugin.mkNeovimPlugin config { attrsOf ( either str (submodule { options = { - action = mkOption { type = types.str; }; + action = mkOption { + type = types.str; + description = "The telescope action to run."; + }; mode = helpers.keymaps.mkModeOption "n"; options = helpers.keymaps.mapConfigOptions; }; diff --git a/plugins/utils/hydra/hydras-option.nix b/plugins/utils/hydra/hydras-option.nix index 3638b38a..13e9372d 100644 --- a/plugins/utils/hydra/hydras-option.nix +++ b/plugins/utils/hydra/hydras-option.nix @@ -112,6 +112,10 @@ in mkOption { type = types.listOf hydraType; default = [ ]; + description = '' + A list of hydra configurations. + See [here](https://github.com/nvimtools/hydra.nvim?tab=readme-ov-file#creating-a-new-hydra). + ''; example = [ { name = "git"; diff --git a/plugins/utils/nix-develop.nix b/plugins/utils/nix-develop.nix index 19279ed2..d7936877 100644 --- a/plugins/utils/nix-develop.nix +++ b/plugins/utils/nix-develop.nix @@ -16,13 +16,26 @@ in package = helpers.mkPluginPackageOption "nix-develop.nvim" pkgs.vimPlugins.nix-develop-nvim; ignoredVariables = mkOption { - type = types.attrsOf types.bool; + type = with types; attrsOf bool; default = { }; + description = "An attrs specifying the variables should be ignored."; + example = { + BASHOPTS = true; + HOME = true; + NIX_BUILD_TOP = true; + SHELL = true; + TMP = true; + }; }; separatedVariables = mkOption { - type = types.attrsOf types.str; + type = with types; attrsOf str; default = { }; + description = "An attrs specifying the separator to use for particular environment variables."; + example = { + PATH = ":"; + XDG_DATA_DIRS = ":"; + }; }; }; diff --git a/plugins/utils/nvim-colorizer.nix b/plugins/utils/nvim-colorizer.nix index 47051cee..2acfe094 100644 --- a/plugins/utils/nvim-colorizer.nix +++ b/plugins/utils/nvim-colorizer.nix @@ -108,18 +108,22 @@ in fileTypes = mkOption { description = "Enable and/or configure highlighting for certain filetypes"; - type = types.nullOr ( - types.listOf ( - types.oneOf [ - types.str - (types.submodule { - options = { - language = mkOption { type = types.str; }; - } // colorizer-options; - }) - ] - ) - ); + type = + with types; + nullOr ( + listOf ( + either str ( + types.submodule { + options = { + language = mkOption { + type = types.str; + description = "The language this configuration should apply to."; + }; + } // colorizer-options; + } + ) + ) + ); default = null; }; diff --git a/plugins/utils/which-key.nix b/plugins/utils/which-key.nix index 4831a3b2..d0e851a5 100644 --- a/plugins/utils/which-key.nix +++ b/plugins/utils/which-key.nix @@ -69,12 +69,21 @@ with lib; window = let spacingOptions = types.submodule { - options = { - top = mkOption { type = types.int; }; - right = mkOption { type = types.int; }; - bottom = mkOption { type = types.int; }; - left = mkOption { type = types.int; }; - }; + options = + genAttrs + [ + "top" + "right" + "bottom" + "left" + ] + ( + n: + mkOption { + type = types.ints.unsigned; + description = "Spacing at the ${n}."; + } + ); }; in { @@ -98,18 +107,26 @@ with lib; let rangeOption = types.submodule { options = { - min = mkOption { type = types.int; }; - max = mkOption { type = types.int; }; + min = mkOption { + type = types.int; + description = "Minimum size."; + }; + max = mkOption { + type = types.int; + description = "Maximum size."; + }; }; }; in { - height = - helpers.defaultNullOpts.mkNullable rangeOption "{min = 4; max = 25;}" - "min and max height of the columns"; - width = - helpers.defaultNullOpts.mkNullable rangeOption "{min = 20; max = 50;}" - "min and max width of the columns"; + height = helpers.defaultNullOpts.mkNullable rangeOption { + min = 4; + max = 25; + } "min and max height of the columns"; + width = helpers.defaultNullOpts.mkNullable rangeOption { + min = 20; + max = 50; + } "min and max width of the columns"; spacing = helpers.defaultNullOpts.mkInt 3 "spacing between columns"; align = helpers.defaultNullOpts.mkEnumFirstDefault [ "left"