From 2be8db54d564fbeebde13417dbb71ee96a2077b8 Mon Sep 17 00:00:00 2001
From: Ching Pei Yang <badnam3o.0@gmail.com>
Date: Sat, 6 Apr 2024 20:33:31 +0000
Subject: [PATCH] docs: developer docs on setupOpts

---
 docs/manual/hacking/additional-plugins.md | 92 +++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/docs/manual/hacking/additional-plugins.md b/docs/manual/hacking/additional-plugins.md
index c70727d..07a972f 100644
--- a/docs/manual/hacking/additional-plugins.md
+++ b/docs/manual/hacking/additional-plugins.md
@@ -31,3 +31,95 @@ You can now reference this plugin using its string name:
 ```nix
 config.vim.startPlugins = ["neodev-nvim"];
 ```
+
+## Modular setup options {#sec-modular-setup-options}
+
+Most plugins is initialized with a call to `require('plugin').setup({...})`.
+
+We use a special function that lets you easily add support for such setup options in a modular way:
+`mkPluginSetupOption`.
+
+Once you have added the source of the plugin as shown above, you can define the setup options like
+this:
+
+```nix
+# in modules/.../your-plugin/your-plugin.nix
+
+{lib, ...}:
+let
+  inherit (lib.types) bool int;
+  inherit (lib.nvim.types) mkPluginSetupOption;
+in {
+  options.vim.your-plugin = {
+    setupOpts = mkPluginSetupOption "plugin name" {
+      enable_feature_a = mkOption {
+        type = bool;
+        default = false;
+        # ...
+      };
+
+      number_option = mkOption {
+        type = int;
+        default = 3;
+        # ...
+      };
+    };
+  };
+}
+```
+
+```nix
+# in modules/.../your-plugin/config.nix
+{lib, config, ...}:
+let
+  cfg = config.vim.your-plugin;
+in {
+  vim.luaConfigRC = lib.nvim.dag.entryAnywhere ''
+    require('plugin-name').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
+  '';
+}
+```
+
+This above config will result in this lua script:
+
+```lua
+require('plugin-name').setup({
+  enable_feature_a = false,
+  number_option = 3,
+})
+```
+
+Now users can set any of the pre-defined option field, and can also add their own fields!
+
+```nix
+# in user's config
+{
+  vim.your-plugin.setupOpts = {
+    enable_feature_a = true;
+    number_option = 4;
+    another_field = "hello";
+    size = { # nested fields work as well
+      top = 10;
+    };
+  };
+}
+```
+
+## Details of toLuaObject {#sec-details-of-toluaobject}
+
+As you've seen above, `toLuaObject` is used to convert our nix attrSet `cfg.setupOpts`, into a lua
+table. Here are some rules of the conversion:
+
+1. nix `null` converts to lua `nil`
+2. number and strings convert to their lua counterparts
+3. nix attrSet/list converts into lua tables
+4. you can write raw lua code using `lib.generators.mkLuaInline`. This function is part of nixpkgs.
+   ```nix
+   vim.your-plugin.setupOpts = {
+     on_init = lib.generators.mkLuaInline ''
+       function()
+         print('we can write lua!')
+       end
+     '';
+   }
+   ```