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

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