From fc4866826c5c2a39046edf8ee9af4ae5310433b0 Mon Sep 17 00:00:00 2001
From: Gabriel Arazas <foodogsquared@foodogsquared.one>
Date: Mon, 13 Jan 2025 09:33:30 +0800
Subject: [PATCH] lib: add nixdoc docstrings

---
 lib/env.nix     | 78 ++++++++++++++++++++++++++++++++++++++--
 lib/modules.nix | 47 +++++++++++++++++++++++-
 lib/utils.nix   | 96 ++++++++++++++++++++++++++++++++++++++++++++++---
 shell.nix       |  1 +
 4 files changed, 215 insertions(+), 7 deletions(-)

diff --git a/lib/env.nix b/lib/env.nix
index b31a4b0..b224520 100644
--- a/lib/env.nix
+++ b/lib/env.nix
@@ -1,11 +1,85 @@
 rec {
-  /*
+  /**
     Given the attrset for evaluating a wrapper-manager module, return a
     derivation containing the wrapper.
+
+    # Arguments
+
+    It has the same arguments as
+    [`wrapperManagerLib.env.eval`](#function-library-wrapperManagerLib.env.eval).
+
+    # Type
+
+    ```
+    build :: Attr -> Derivation
+    ```
+
+    # Example
+
+    ```
+    build {
+      pkgs = import <nixpkgs> { };
+      modules = [
+        ./wrapper-manager-config.nix
+        ./modules/wrapper-manager
+      ];
+    }
+    =>
+    <drv>
+    ```
   */
   build = args: (eval args).config.build.toplevel;
 
-  # Evaluate a wrapper-manager configuration.
+  /**
+    Evaluate a wrapper-manager configuration.
+
+    # Arguments
+
+    Its argument only expects a sole attribute set with the following
+    attributes:
+
+    pkgs
+    : A nixpkgs instance.
+
+    lib
+    : The nixpkgs library subset. Defaults to `pkgs.lib` from the given nixpkgs
+    instance.
+
+    modules
+    : A list of additional wrapper-manager modules to be imported (typically
+    the wrapper-manager configuration and additional modules) for the final
+    configuration.
+
+    specialArgs
+    : An additional set of module arguments that can be used in `imports`.
+
+    # Type
+
+    ```
+    eval :: Attr -> Attr
+    ```
+
+    # Example
+
+    ```
+    eval {
+      pkgs = import <nixpkgs> { };
+      modules = [
+        ./wrapper-manager-config.nix
+        ./modules/wrapper-manager
+      ];
+    }
+    =>
+    {
+      _module = { ... };
+      _type = "configuration";
+      class = null;
+      config = { ... };
+      options = { ... };
+      extendModules = <func>;
+    }
+    ```
+  */
   eval =
     {
       pkgs,
diff --git a/lib/modules.nix b/lib/modules.nix
index ba8c2b3..d64d640 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -11,10 +11,55 @@
 }:
 
 rec {
-  /*
+  /**
     Make a wrapper-manager wrapper config containing a sub-wrapper that wraps
     another program. Several examples of this includes sudo, Bubblewrap, and
     Gamescope.
+
+    # Arguments
+
+    Its arguments is a sole attribute set with the following expected
+    attributes:
+
+    arg0
+    : Similar to `wrappers.<name>.arg0` from wrapper-manager module, it is a
+    store path containing an executable used as the main program of the wrapper.
+
+    under
+    : Similar to `arg0` but for the wraparound (e.g., sudo, doas, Bubblewrap).
+
+    underFlags
+    : Arguments of the wraparound. Defaults to an empty list.
+
+    underSeparator
+    : An optional string acting as the separator between the wraparound's
+    arguments and the arg0's arguments.
+
+    Note that the argument attrset can contain any attribute. The attrset is
+    then separated as a module and an additional module using the above
+    attributes.
+
+    # Type
+
+    ```
+    makeWraparound :: Attr -> Module
+    ```
+
+    # Example
+
+    ```
+    makeWraparound {
+      arg0 = lib.getExe' pkgs.hello "hello";
+      appendArgs = [ "--traditional" ];
+      under = lib.getExe' pkgs.sudo "sudo";
+      underFlags = [ "-u" "admin" ];
+    }
+    =>
+    {
+      _type = "merge";
+      contents = [ ... ];
+    }
+    ```
   */
   makeWraparound =
     {
diff --git a/lib/utils.nix b/lib/utils.nix
index d749913..42c2b24 100644
--- a/lib/utils.nix
+++ b/lib/utils.nix
@@ -5,27 +5,115 @@
 }:
 
 rec {
-  /*
+  /**
     Given a list of derivations, return a list of the store path with the `bin`
     output (or at least with "/bin" in each of the paths).
+
+    # Arguments
+
+    drvs
+    : A list of derivations.
+
+    # Type
+
+    ```
+    getBin :: [ Derivation ] -> [ Path ]
+    ```
+
+    # Examples
+
+    ```
+    getBin (with pkgs; [ hello coreutils ])
+    =>
+    [
+      "/nix/store/HASH-hello/bin"
+      "/nix/store/HASH-coreutils/bin"
+    ]
+    ```
   */
   getBin = drvs: builtins.map (v: lib.getBin v) drvs;
 
-  /*
+  /**
     Given a list of derivations, return a list of the store paths with the
     `libexec` appended.
+
+    # Arguments
+
+    drvs
+    : A list of derivations.
+
+    # Type
+
+    ```
+    getLibexec :: [ Derivation ] -> [ Path ]
+    ```
+
+    # Examples
+
+    ```
+    getLibexec (with pkgs; [ hello coreutils ])
+    =>
+    [
+      "/nix/store/HASH-hello/libexec"
+      "/nix/store/HASH-coreutils/libexec"
+    ]
+    ```
   */
   getLibexec = drvs: builtins.map (v: "${v}/libexec") drvs;
 
-  /*
+  /**
     Given a list of derivations, return a list of the store paths appended with
     `/etc/xdg` suitable as part of the XDG_CONFIG_DIRS environment variable.
+
+    # Arguments
+
+    drvs
+    : A list of derivations.
+
+    # Type
+
+    ```
+    getXdgConfigDirs :: [ Derivation ] -> [ Path ]
+    ```
+
+    # Examples
+
+    ```
+    getXdgConfigDirs (with pkgs; [ hello coreutils ])
+    =>
+    [
+      "/nix/store/HASH-hello/etc/xdg"
+      "/nix/store/HASH-coreutils/etc/xdg"
+    ]
+    ```
   */
   getXdgConfigDirs = drvs: builtins.map (v: "${v}/etc/xdg") drvs;
 
-  /*
+  /**
     Given a list of derivations, return a list of store paths appended with
     `/share` suitable as part of the XDG_DATA_DIRS environment variable.
+
+    # Arguments
+
+    drvs
+    : A list of derivations.
+
+    # Type
+
+    ```
+    getXdgDataDirs :: [ Derivation ] -> [ Path ]
+    ```
+
+    # Examples
+
+    ```
+    getXdgDataDirs (with pkgs; [ hello coreutils ])
+    =>
+    [
+      "/nix/store/HASH-hello/share"
+      "/nix/store/HASH-coreutils/share"
+    ]
+    ```
   */
   getXdgDataDirs = drvs: builtins.map (v: "${v}/share") drvs;
 }
diff --git a/shell.nix b/shell.nix
index 55b4381..7840ddc 100644
--- a/shell.nix
+++ b/shell.nix
@@ -16,6 +16,7 @@ pkgs.mkShell {
     npins
     treefmt
     nixfmt-rfc-style
+    nixdoc
 
     # For easy validation of the test suite.
     yajsv