From f4a7447d27d3c43c59555c053c203f1abb45e899 Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Thu, 15 May 2025 16:12:26 +0100
Subject: [PATCH] lib/util: move docs from `lib/index` to doc-comments

Moved all function-specific docs from `docs/lib/index.md` into RFC145
doc-comments.

Added `lib.nixvim.lua.toLuaObject` to hold the public docs and serve as
a stable impl of `toLua'` in case we decide to change its defaults.
---
 docs/lib/index.md | 44 ------------------------------------------
 lib/default.nix   |  2 +-
 lib/to-lua.nix    | 15 +++++++++++++++
 lib/utils.nix     | 49 ++++++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 64 insertions(+), 46 deletions(-)

diff --git a/docs/lib/index.md b/docs/lib/index.md
index 827d346c..e52f98a6 100644
--- a/docs/lib/index.md
+++ b/docs/lib/index.md
@@ -65,47 +65,3 @@ This can be achieved using the lib overlay, available via the `<nixvim>.lib.over
     };
 }
 ```
-
-## Common helper functions
-
-A certain number of helpers are defined that can be useful:
-
-- `helpers.emptyTable`: An empty lua table `{}` that will be included in the final lua configuration.
-  This is equivalent to `{__empty = {};}`. This form can allow to do `option.__empty = {}`.
-
-- `helpers.mkRaw str`: Write the string `str` as raw lua in the final lua configuration.
-  This is equivalent to `{__raw = "lua code";}`. This form can allow to do `option.__raw = "lua code"`.
-
-- `helpers.toLuaObject obj`: Create a string representation of the Nix object. Useful to define your own plugins.
-
-- `helpers.listToUnkeyedAttrs list`: Transforms a list to an "unkeyed" attribute set.
-
-  This allows to define mixed table/list in lua:
-
-  ```nix
-    (listToUnkeyedAttrs ["a" "b"]) // {foo = "bar";}
-  ```
-
-  Resulting in the following lua:
-
-  ```lua
-    {"a", "b", [foo] = "bar"}
-  ```
-
-- `helpers.enableExceptInTests`: Evaluates to `true`, except in `mkTestDerivationFromNixvimModule`
-  where it evaluates to `false`. This allows to skip instantiating plugins that can't be run in tests.
-
-- `helpers.toRawKeys attrs`: Convert the keys of the given `attrs` to raw lua.
-  ```nix
-    toRawKeys {foo = 1; bar = "hi";}
-  ```
-  will translate in lua to:
-  ```lua
-    {[foo] = 1, [bar] = 2,}
-  ```
-  Otherwise, the keys of a regular `attrs` will be interpreted as lua string:
-  ```lua
-    {['foo'] = 1, ['bar'] = 2,}
-    -- which is the same as
-    {foo = 1, bar = 2,}
-  ```
diff --git a/lib/default.nix b/lib/default.nix
index b0897f50..2b86d67a 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -103,7 +103,7 @@ lib.makeExtensible (
       wrapVimscriptForLua
       ;
 
-    toLuaObject = self.lua.toLua;
+    inherit (self.lua) toLuaObject;
     mkLuaInline = self.lua.mkInline;
 
     # TODO: Removed 2024-12-21
diff --git a/lib/to-lua.nix b/lib/to-lua.nix
index 4c4c7434..3319a054 100644
--- a/lib/to-lua.nix
+++ b/lib/to-lua.nix
@@ -38,6 +38,21 @@ rec {
   # Whether the value is a lua-inline type
   isInline = v: v._type or null == "lua-inline";
 
+  /**
+    Serialise a nix value as a lua object.
+
+    Useful for defining your own plugins or structured config.
+
+    # Type
+
+    ```
+    toLuaObject :: Any -> String
+    ```
+  */
+  toLuaObject =
+    # toLua' with backwards-compatible options
+    toLua' { };
+
   # toLua' with default options, aliased as toLuaObject at the top-level
   toLua = toLua' { };
 
diff --git a/lib/utils.nix b/lib/utils.nix
index 98680c00..d218220b 100644
--- a/lib/utils.nix
+++ b/lib/utils.nix
@@ -3,20 +3,49 @@
   _nixvimTests,
 }:
 rec {
+  /**
+    Transforms a list to an _"unkeyed"_ attribute set.
+
+    This allows to define mixed table/list in lua:
+
+    ```nix
+    listToUnkeyedAttrs ["a" "b"] // { foo = "bar"; }
+    ```
+
+    Resulting in the following lua:
+
+    ```lua
+    {"a", "b", foo = "bar"}
+    ```
+  */
   listToUnkeyedAttrs =
     list:
     builtins.listToAttrs (lib.lists.imap0 (idx: lib.nameValuePair "__unkeyed-${toString idx}") list);
 
+  /**
+    Usually `true`, except when nixvim is being evaluated by
+    `mkTestDerivationFromNixvimModule`, where it is `false`.
+
+    This can be used to dynamically enable plugins that can't be run in the
+    test environment.
+  */
   # TODO: replace and deprecate
   # We shouldn't need to use another instance of `lib` when building a test drv
   enableExceptInTests = !_nixvimTests;
 
+  /**
+    An empty lua table `{ }` that will be included in the final lua configuration.
+
+    This is equivalent to `{ __empty = { }; }`.
+    This form can allow to do `option.__empty = { }`.
+  */
   emptyTable = {
+    # Keep nested to bind docs to `emptyTable`, not `__empty`.
     "__empty" = null;
   };
 
   /**
-    Turn all the keys of an attrs into raw lua.
+    Convert the keys of the given attrset to _"raw lua"_.
 
     # Example
 
@@ -25,6 +54,18 @@ rec {
     => { __rawKey__foo = 1; __rawKey__bar = 2; }
     ```
 
+    Resulting in the following lua:
+
+    ```lua
+    {[foo] = 1, [bar] = 2}
+    ```
+
+    If "raw keys" are **not** used, the attr names are treated as string keys:
+
+    ```lua
+    {foo = 1, bar = 2}
+    ```
+
     # Type
 
     ```
@@ -56,6 +97,12 @@ rec {
   */
   mkRawKey = n: v: toRawKeys { "${n}" = v; };
 
+  /**
+    Write the string `str` as raw lua in the final lua configuration.
+
+    This is equivalent to `{ __raw = "lua code"; }`.
+    This form can allow to do `option.__raw = "lua code"`.
+  */
   mkRaw =
     r:
     if r == null || r == "" then