diff --git a/doc/builders/special.xml b/doc/builders/special.xml
index 525eb71abfe7..c97113481981 100644
--- a/doc/builders/special.xml
+++ b/doc/builders/special.xml
@@ -6,6 +6,7 @@
   This chapter describes several special builders.
  </para>
  <xi:include href="special/fhs-environments.section.xml" />
+ <xi:include href="special/makesetuphook.section.xml" />
  <xi:include href="special/mkshell.section.xml" />
  <xi:include href="special/darwin-builder.section.xml" />
 </chapter>
diff --git a/doc/builders/special/makesetuphook.section.md b/doc/builders/special/makesetuphook.section.md
new file mode 100644
index 000000000000..90d75c5491cf
--- /dev/null
+++ b/doc/builders/special/makesetuphook.section.md
@@ -0,0 +1,37 @@
+# pkgs.makeSetupHook {#sec-pkgs.makeSetupHook}
+
+`pkgs.makeSetupHook` is a builder that produces hooks that go in to `nativeBuildInputs`
+
+## Usage {#sec-pkgs.makeSetupHook-usage}
+
+```nix
+pkgs.makeSetupHook {
+  name = "something-hook";
+  propagatedBuildInputs = [ pkgs.commandsomething ];
+  depsTargetTargetPropagated = [ pkgs.libsomething ];
+} ./script.sh
+```
+
+#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash
+
+```nix
+pkgs.makeSetupHook {
+    name = "run-hello-hook";
+    propagatedBuildInputs = [ pkgs.hello ];
+    substitutions = { shell = "${pkgs.bash}/bin/bash"; };
+    passthru.tests.greeting = callPackage ./test { };
+    meta.platforms = lib.platforms.linux;
+} (writeScript "run-hello-hook.sh" ''
+    #!@shell@
+    hello
+'')
+```
+
+## Attributes
+
+* `name` Set the name of the hook.
+* `propagatedBuildInputs` Runtime dependencies (such as binaries) of the hook.
+* `depsTargetTargetPropagated` Non-binary dependencies.
+* `meta`
+* `passthru`
+* `substitutions` Variables for `substituteAll`
diff --git a/pkgs/build-support/trivial-builders.nix b/pkgs/build-support/trivial-builders.nix
index c7cc61262a0a..413ed65852f5 100644
--- a/pkgs/build-support/trivial-builders.nix
+++ b/pkgs/build-support/trivial-builders.nix
@@ -593,34 +593,7 @@ rec {
     in linkFarm name (map mkEntryFromDrv drvs);
 
 
-  /*
-   * Make a package that just contains a setup hook with the given contents.
-   * This setup hook will be invoked by any package that includes this package
-   * as a buildInput. Optionally takes a list of substitutions that should be
-   * applied to the resulting script.
-   *
-   * Examples:
-   * # setup hook that depends on the hello package and runs ./myscript.sh
-   * myhellohook = makeSetupHook { propagatedBuildInputs = [ hello ]; } ./myscript.sh;
-   *
-   * # writes a Linux-exclusive setup hook where @bash@ myscript.sh is substituted for the
-   * # bash interpreter.
-   * myhellohookSub = makeSetupHook {
-   *                 name = "myscript-hook";
-   *                 propagatedBuildInputs = [ hello ];
-   *                 substitutions = { bash = "${pkgs.bash}/bin/bash"; };
-   *                 meta.platforms = lib.platforms.linux;
-   *               } ./myscript.sh;
-   *
-   * # setup hook with a package test
-   * myhellohookTested = makeSetupHook {
-   *                 name = "myscript-hook";
-   *                 propagatedBuildInputs = [ hello ];
-   *                 substitutions = { bash = "${pkgs.bash}/bin/bash"; };
-   *                 meta.platforms = lib.platforms.linux;
-   *                 passthru.tests.greeting = callPackage ./test { };
-   *               } ./myscript.sh;
-   */
+  # docs in doc/builders/special/makesetuphook.section.md
   makeSetupHook =
     { name ? lib.warn "calling makeSetupHook without passing a name is deprecated." "hook"
     , deps ? [ ]