From 940f8171191b481f824c93eb45e0bca099566f26 Mon Sep 17 00:00:00 2001
From: Zitrone <general@dev.quantenzitrone.eu>
Date: Sun, 27 Oct 2024 13:29:43 +0100
Subject: [PATCH] pkgs.wrapFish: document with docstrings

it is also (a bit less verbosely) documented in the manual
this documentation will eventually replace the one in the manual
---
 pkgs/shells/fish/wrapper.nix | 89 ++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)

diff --git a/pkgs/shells/fish/wrapper.nix b/pkgs/shells/fish/wrapper.nix
index 7831e861e2da..29a7a1ce9bdf 100644
--- a/pkgs/shells/fish/wrapper.nix
+++ b/pkgs/shells/fish/wrapper.nix
@@ -6,6 +6,95 @@
 }:
 
 lib.makeOverridable (
+  /**
+    Creates a wrapped fish shell binary with some plugins, completions,
+    configuration snippets and functions sourced from the function
+    arguments.
+
+    This can for example be used as a convenient way to test fish plugins
+    and scripts without having to alter the environment.
+
+    # Type
+
+    ```pseudocode
+    wrapFish :: {
+      completionDirs :: [Path] ?,
+      functionDirs :: [Path] ?,
+      confDirs :: [Path] ?,
+      pluginPkgs :: [Derivation] ?,
+      localConfig :: String ?,
+      shellAliases :: {
+        [ N :: T ] :: String
+      } ?,
+      runtimeInputs :: [Derivation] ?,
+    } -> Derivation
+    ```
+
+    # Example
+
+    ::: {.example}
+    ```nix
+    wrapFish {
+      pluginPkgs = with fishPlugins; [
+        pure
+        foreign-env
+      ];
+      completionDirs = [ ];
+      functionDirs = [ ];
+      confDirs = [ "/path/to/some/fish/init/dir/" ];
+      shellAliases = {
+        hello = "echo 'Hello World!'";
+        bye = "echo 'Bye World!'; exit";
+      };
+      runtimeInputs = with pkgs; [
+        curl
+        w3m
+      ];
+    }
+    ```
+    :::
+
+    # Arguments
+
+    All arguments are optional.
+
+    ## `completionDirs` (list of paths)
+
+    Directories containing fish completions which will be prepended to
+    {env}`fish_complete_paths` in the environment of the resulting wrapped
+    fish binary.
+
+    ## `functionDirs` (list of paths)
+
+    Directories containing fish functions which will be prepended to
+    {env}`fish_function_path` in the environment of the resulting wrapped
+    fish binary.
+
+    ## `confDirs` (list of paths)
+
+    Directories containing fish code which will be sourced by the resulting
+    wrapped fish binary.
+
+    ## `pluginPkgs` (list of derivations)
+
+    Derivations, usually from the package set `fishPlugins`, that will be
+    added to the resulting wrapped fish binary.
+
+    ## `localConfig` (string)
+
+    String containing a fish script which will be sourced by the resulting
+    wrapped fish binary.
+
+    ## `shellAliases` (attribute set of strings)
+
+    Shell aliases that will be made available in the resulting wrapped fish
+    binary.
+
+    ## `runtimeInputs` (list of derivations)
+
+    A list of Derivations that will be added to the {env}`PATH` of the
+    resulting wrapped fish binary.
+  */
   {
     completionDirs ? [ ],
     functionDirs ? [ ],