From f11c43612f5d9199c0d16477ab3bd9b58a79cb26 Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Thu, 20 Nov 2025 03:09:13 +0000
Subject: [PATCH] lib/overlay: rename and document overlay arguments

Rename the overlay arguments from the conventional `final: prev:` to the
more explicit `lib: prevLib:`, reflecting that this overlay operates
only on the Nixpkgs lib, rather than a full package set.

Add a doccomment explaining how the overlay is intended to be applied
(via `lib.extend`) and what each argument represents.

Improved inline comments in the overlay.
---
 lib/overlay.nix | 40 +++++++++++++++++++++++++++++++++-------
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/lib/overlay.nix b/lib/overlay.nix
index 18e7825a..92e453e8 100644
--- a/lib/overlay.nix
+++ b/lib/overlay.nix
@@ -1,14 +1,40 @@
 { flake }:
-final: prev: {
-  # Include our custom lib
+
+/**
+  Overlay function extending the Nixpkgs `lib` with Nixvim's additions.
+
+  This function is intended to be passed to `lib.extend`.
+
+  # Examples
+
+  Importing the file directly:
+  ```
+  lib.extend (import ./overlay.nix { flake = nixvim; })
+  ```
+
+  Using the overlay from flake outputs:
+  ```
+  lib.extend nixvim.lib.overlay
+  ```
+
+  # Inputs
+
+  `lib`
+  : The final lib instance; the fixpoint of all extensions, including this one.
+
+  `prevLib`
+  : The lib instance prior to applying this overlay.
+*/
+lib: prevLib: {
+  # Add Nixvim's section to the lib
   nixvim = flake.lib.nixvim.override {
-    lib = final;
+    inherit lib;
     _isExtended = true;
   };
 
-  # Merge in our maintainers
-  maintainers = prev.maintainers // import ./maintainers.nix;
+  # Extend the maintainers set with Nixvim-specific maintainers
+  maintainers = prevLib.maintainers // import ./maintainers.nix;
 
-  # Merge in our custom types
-  types = prev.types // import ./types.nix { lib = final; };
+  # Extend lib.types with Nixvim's custom types
+  types = prevLib.types // import ./types.nix { inherit lib; };
 }