misc: ensure all options have a description

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.
+              '';
+            };
           };
         })
       ))

modules/keymaps.nix

@@ -11,6 +11,7 @@ with lib;
     keymaps = mkOption {
       type = types.listOf helpers.keymaps.mapOptionSubmodule;
       default = [ ];
+      description = "Nixvim keymaps.";
       example = [
         {
           key = "<C-m>";

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

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

plugins/languages/treesitter/treesitter.nix

@@ -80,6 +80,7 @@ in
             mkOption {
               type = types.str;
               inherit default;
+              description = "Key shortcut";
             };
         in
         {

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) ''

plugins/snippets/luasnip/default.nix

@@ -71,18 +71,23 @@ in
 
     fromVscode = mkOption {
       default = [ ];
-      example = ''
+      example = literalExpression ''
         [
-          {}
+          { }
-          {
+          { paths = ./path/to/snippets; }
-            paths = ./path/to/snippets;
+        ]'';
-          }
+      description = ''
-        ]
+        List of custom vscode style snippets to load.
-        # generates:
+
-        #
+        For example,
-        # require("luasnip.loaders.from_vscode").lazy_load({})
+        ```nix
-        # require("luasnip.loaders.from_vscode").lazy_load({['paths'] = {'/nix/store/.../path/to/snippets'}})
+          [ {} { 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;
     };

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 =

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;
             };

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";

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 = ":";
+      };
     };
   };
 

plugins/utils/nvim-colorizer.nix

@@ -108,18 +108,22 @@ in
 
       fileTypes = mkOption {
         description = "Enable and/or configure highlighting for certain filetypes";
-        type = types.nullOr (
+        type =
-          types.listOf (
+          with types;
-            types.oneOf [
+          nullOr (
-              types.str
+            listOf (
-              (types.submodule {
+              either str (
-                options = {
+                types.submodule {
-                  language = mkOption { type = types.str; };
+                  options = {
-                } // colorizer-options;
+                    language = mkOption {
-              })
+                      type = types.str;
-            ]
+                      description = "The language this configuration should apply to.";
-          )
+                    };
-        );
+                  } // colorizer-options;
+                }
+              )
+            )
+          );
         default = null;
       };
 

plugins/utils/which-key.nix

@@ -69,12 +69,21 @@ with lib;
     window =
       let
         spacingOptions = types.submodule {
-          options = {
+          options =
-            top = mkOption { type = types.int; };
+            genAttrs
-            right = mkOption { type = types.int; };
+              [
-            bottom = mkOption { type = types.int; };
+                "top"
-            left = mkOption { type = types.int; };
+                "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; };
+            min = mkOption {
-            max = mkOption { type = types.int; };
+              type = types.int;
+              description = "Minimum size.";
+            };
+            max = mkOption {
+              type = types.int;
+              description = "Maximum size.";
+            };
           };
         };
       in
       {
-        height =
+        height = helpers.defaultNullOpts.mkNullable rangeOption {
-          helpers.defaultNullOpts.mkNullable rangeOption "{min = 4; max = 25;}"
+          min = 4;
-            "min and max height of the columns";
+          max = 25;
-        width =
+        } "min and max height of the columns";
-          helpers.defaultNullOpts.mkNullable rangeOption "{min = 20; max = 50;}"
+        width = helpers.defaultNullOpts.mkNullable rangeOption {
-            "min and max width of the columns";
+          min = 20;
+          max = 50;
+        } "min and max width of the columns";
         spacing = helpers.defaultNullOpts.mkInt 3 "spacing between columns";
         align = helpers.defaultNullOpts.mkEnumFirstDefault [
           "left"