lib: add RFC-145 nixdoc comments to extended library functions

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I41c4b2cb70512699a044578fa88eb8266a6a6964

lib/binds.nix

@@ -5,6 +5,28 @@
   inherit (lib.attrsets) isAttrs mapAttrs;
 
   binds = rec {
+    /**
+      Create a silent Lua keybinding wrapped in `mkIf` to guard against null keys.
+
+      # Type
+
+      ```
+      mkLuaBinding :: String | Null -> String -> String -> AttrSet
+      ```
+
+      # Arguments
+
+      - `key`: The key sequence to bind, or `null` to disable.
+      - `action`: Lua expression to execute on keypress.
+      - `desc`: Human-readable description of the binding.
+
+      # Example
+
+      ```nix
+      mkLuaBinding "<leader>f" "require('telescope').find_files" "Find files"
+      => { "<leader>f" = { action = "require('telescope').find_files"; desc = "Find files"; lua = true; silent = true; }; }
+      ```
+    */
     mkLuaBinding = key: action: desc:
       mkIf (key != null) {
         "${key}" = {
@@ -14,6 +36,28 @@
         };
       };
 
+    /**
+      Create a silent expression-mode Lua keybinding wrapped in `mkIf`.
+
+      # Type
+
+      ```
+      mkExprBinding :: String | Null -> String -> String -> AttrSet
+      ```
+
+      # Arguments
+
+      - `key`: The key sequence to bind, or `null` to disable.
+      - `action`: Lua expression evaluated as a Vim expression.
+      - `desc`: Human-readable description of the binding.
+
+      # Example
+
+      ```nix
+      mkExprBinding "<C-n>" "v:count == 0 ? 'j' : 'gj'" "Smart down"
+      => { "<C-n>" = { action = "v:count == 0 ? 'j' : 'gj'"; desc = "Smart down"; lua = true; silent = true; expr = true; }; }
+      ```
+    */
     mkExprBinding = key: action: desc:
       mkIf (key != null) {
         "${key}" = {
@@ -24,6 +68,28 @@
         };
       };
 
+    /**
+      Create a silent (non-Lua) keybinding wrapped in `mkIf` to guard against null keys.
+
+      # Type
+
+      ```
+      mkBinding :: String | Null -> String -> String -> AttrSet
+      ```
+
+      # Arguments
+
+      - `key`: The key sequence to bind, or `null` to disable.
+      - `action`: Vimscript command or mapping string to execute.
+      - `desc`: Human-readable description of the binding.
+
+      # Example
+
+      ```nix
+      mkBinding "<leader>w" ":w<CR>" "Save file"
+      => { "<leader>w" = { action = ":w<CR>"; desc = "Save file"; silent = true; }; }
+      ```
+    */
     mkBinding = key: action: desc:
       mkIf (key != null) {
         "${key}" = {
@@ -32,17 +98,58 @@
         };
       };
 
+    /**
+      Build a nullable string NixOS option suitable for storing a keybinding value.
+
+      # Type
+
+      ```
+      mkMappingOption :: String -> String | Null -> Option
+      ```
+
+      # Arguments
+
+      - `description`: Documentation string for the option.
+      - `default`: Default key value, or `null` for no binding.
+
+      # Example
+
+      ```nix
+      mkMappingOption "Toggle file tree" "<leader>e"
+      => mkOption { type = nullOr str; default = "<leader>e"; description = "Toggle file tree"; }
+      ```
+    */
     mkMappingOption = description: default:
       mkOption {
         type = nullOr str;
         inherit default description;
       };
 
-    # Utility function that takes two attrsets:
-    # { someKey = "some_value" } and
-    # { someKey = { description = "Some Description"; }; }
-    # and merges them into
-    # { someKey = { value = "some_value"; description = "Some Description"; }; }
+    /**
+      Merge actual mapping values with their description metadata.
+
+      Takes two attribute sets: one mapping keys to values and another mapping
+      keys to `{ description }` records. Produces an attribute set mapping
+      keys to `{ value; description }` records. Nesting is handled recursively.
+
+      # Type
+
+      ```
+      addDescriptionsToMappings :: AttrSet -> AttrSet -> AttrSet
+      ```
+
+      # Arguments
+
+      - `actualMappings`: Attribute set of key → value pairs.
+      - `mappingDefinitions`: Attribute set of key → `{ description }` pairs.
+
+      # Example
+
+      ```nix
+      addDescriptionsToMappings { someKey = "some_value"; } { someKey = { description = "Some Description"; }; }
+      => { someKey = { value = "some_value"; description = "Some Description"; }; }
+      ```
+    */
     addDescriptionsToMappings = actualMappings: mappingDefinitions:
       mapAttrs (name: value: let
         isNested = isAttrs value;
@@ -57,17 +164,126 @@
         returnedValue)
       actualMappings;
 
+    /**
+      Create a non-Lua keybinding from a structured binding record produced by `mkMappingOption`.
+
+      # Type
+
+      ```
+      mkSetBinding :: { value :: String | Null; description :: String } -> String -> AttrSet
+      ```
+
+      # Arguments
+
+      - `binding`: Binding record with `value` (key) and `description` fields.
+      - `action`: Vimscript command or mapping string to execute.
+
+      # Example
+
+      ```nix
+      mkSetBinding { value = "<leader>w"; description = "Save file"; } ":w<CR>"
+      => mkBinding "<leader>w" ":w<CR>" "Save file"
+      ```
+    */
     mkSetBinding = binding: action:
       mkBinding binding.value action binding.description;
 
+    /**
+      Create an expression-mode Lua keybinding from a structured binding record.
+
+      # Type
+
+      ```
+      mkSetExprBinding :: { value :: String | Null; description :: String } -> String -> AttrSet
+      ```
+
+      # Arguments
+
+      - `binding`: Binding record with `value` (key) and `description` fields.
+      - `action`: Lua expression evaluated as a Vim expression.
+
+      # Example
+
+      ```nix
+      mkSetExprBinding { value = "<C-n>"; description = "Smart down"; } "v:count == 0 ? 'j' : 'gj'"
+      => mkExprBinding "<C-n>" "v:count == 0 ? 'j' : 'gj'" "Smart down"
+      ```
+    */
     mkSetExprBinding = binding: action:
       mkExprBinding binding.value action binding.description;
 
+    /**
+      Create a silent Lua keybinding from a structured binding record.
+
+      # Type
+
+      ```
+      mkSetLuaBinding :: { value :: String | Null; description :: String } -> String -> AttrSet
+      ```
+
+      # Arguments
+
+      - `binding`: Binding record with `value` (key) and `description` fields.
+      - `action`: Lua expression to execute on keypress.
+
+      # Example
+
+      ```nix
+      mkSetLuaBinding { value = "<leader>f"; description = "Find files"; } "require('telescope').find_files"
+      => mkLuaBinding "<leader>f" "require('telescope').find_files" "Find files"
+      ```
+    */
     mkSetLuaBinding = binding: action:
       mkLuaBinding binding.value action binding.description;
 
+    /**
+      Apply `mkDefault` to every value in an attribute set.
+
+      Useful for lowering the priority of a set of option defaults so they can
+      be overridden by user configuration.
+
+      # Type
+
+      ```
+      pushDownDefault :: AttrSet -> AttrSet
+      ```
+
+      # Arguments
+
+      - `attr`: Attribute set whose values should be wrapped with `mkDefault`.
+
+      # Example
+
+      ```nix
+      pushDownDefault { a = true; b = "hello"; }
+      => { a = mkDefault true; b = mkDefault "hello"; }
+      ```
+    */
     pushDownDefault = attr: mapAttrs (_: mkDefault) attr;
 
+    /**
+      Build a keymap record by merging extra options with mode, key, and action fields.
+
+      # Type
+
+      ```
+      mkKeymap :: String -> String -> String -> AttrSet -> AttrSet
+      ```
+
+      # Arguments
+
+      - `mode`: Vim mode string (e.g. `"n"`, `"v"`, `"i"`).
+      - `key`: Key sequence to bind.
+      - `action`: Action to execute on keypress.
+      - `opt`: Extra options merged into the resulting record.
+
+      # Example
+
+      ```nix
+      mkKeymap "n" "<leader>w" ":w<CR>" { silent = true; }
+      => { mode = "n"; key = "<leader>w"; action = ":w<CR>"; silent = true; }
+      ```
+    */
     mkKeymap = mode: key: action: opt: opt // {inherit mode key action;};
   };
 in