doc: move writeShellApplication param docs to manual

doc/build-helpers/trivial-build-helpers.chapter.md

@@ -734,7 +734,80 @@ Some basic Bash options are set by default (`errexit`, `nounset`, and `pipefail`
 Extra arguments may be passed to `stdenv.mkDerivation` by setting `derivationArgs`; note that variables set in this manner will be set when the shell script is _built,_ not when it's run.
 Runtime environment variables can be set with the `runtimeEnv` argument.
 
-For example, the following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl`:
+`writeShellApplication` has the following arguments:
+
+`name` (String)
+
+: The name of the script to write.
+
+`text` (String)
+
+: The shell script's text, not including a shebang.
+
+`runtimeInputs` (List of derivations or strings, _optional_)
+
+: Inputs to add to the shell script's `$PATH` at runtime.
+
+  Each elements can either be a normal derivation, or a string containing a path, in which case it will be suffixed with `/bin` to create a `PATH` expression (see [`lib.strings.makeBinPath`](#function-library-lib.strings.makeBinPath) for more information).
+
+`runtimeEnv` (Attribute set, _optional_)
+
+: Extra environment variables to set at runtime.
+
+`checkPhase` (String, _optional_)
+
+: The `checkPhase` to run.
+
+  The script path will be given as `$target` in the `checkPhase`
+
+  _Default behavior:_ run [`shellcheck`](https://github.com/koalaman/shellcheck) (on supported platforms) and `bash -n` (check syntax but don't execute commands).
+
+`excludeShellChecks` (List of strings, _optional_)
+
+: Checks to exclude when running `shellcheck`.
+
+  For example, `excludeShellChecks = [ "SC2016" ]` would prevent `shellcheck` from reporting `SC2016`, but would still detect any other problems.
+
+  See [the `shellcheck` wiki](https://www.shellcheck.net/wiki/) for a list of checks.
+
+`extraShellCheckFlags` (List of strings, _optional_)
+
+: Extra command-line flags to pass to `shellcheck`.
+
+`bashOptions` (List of strings, _optional_)
+
+: Bash options to activate with `set -o` at the start of the script
+
+  _Default:_ `[ "errexit" "nounset" "pipefail" ]`, which means:
+  1. A failing command inside of a command list or pipeline will make the script exit, except if used as a conditional (inside a `while`, `if`, `&&`, `||`, etc.);
+  2. Any attempt to expand an undefined variable will make the script exit.
+
+`inheritPath` (Bool, _optional_)
+
+: Whether the script will inherit the PATH from its parent environment.
+
+  _Default:_ `true`
+
+`meta` (Attribute set, _optional_)
+
+: `stdenv.mkDerivation`'s [`meta`](#chap-meta) argument
+
+`passthru` (Attribute set, _optional_)
+
+: `stdenv.mkDerivation`'s [`passthru`](#chap-passthru) argument
+
+`derivationArgs` (Attribute set, _optional_)
+
+: Extra arguments to pass to [`stdenv.mkDerivation`](#chap-stdenv)
+
+  ::: {.caution}
+  Certain derivation attributes are also set internally, so overriding those could cause problems.
+  :::
+
+::: {.example #ex-writeShellApplication}
+# Usage of `writeShellApplication`
+
+The following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl`
 
 ```nix
 writeShellApplication {
@@ -750,6 +823,7 @@ writeShellApplication {
   '';
 }
 ```
+:::
 
 ## `symlinkJoin` {#trivial-builder-symlinkJoin}
 

doc/redirects.json

@@ -119,6 +119,9 @@
   "ex-testEqualArrayOrMap-test-function-add-cowbell": [
     "index.html#ex-testEqualArrayOrMap-test-function-add-cowbell"
   ],
+  "ex-writeShellApplication": [
+    "index.html#ex-writeShellApplication"
+  ],
   "friction-graphics": [
     "index.html#friction-graphics"
   ],

pkgs/build-support/trivial-builders/default.nix

@@ -241,98 +241,25 @@ rec {
       meta.mainProgram = name;
     };
 
-  # TODO: move parameter documentation to the Nixpkgs manual
   # See doc/build-helpers/trivial-build-helpers.chapter.md
   # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-writeShellApplication
   writeShellApplication =
     {
-      /*
-         The name of the script to write.
-
-         Type: String
-      */
       name,
-      /*
-         The shell script's text, not including a shebang.
-
-         Type: String
-      */
       text,
-      /*
-         Inputs to add to the shell script's `$PATH` at runtime.
-
-         Type: [String|Derivation]
-      */
       runtimeInputs ? [ ],
-      /*
-         Extra environment variables to set at runtime.
-
-         Type: AttrSet
-      */
       runtimeEnv ? null,
-      /*
-         `stdenv.mkDerivation`'s `meta` argument.
-
-         Type: AttrSet
-      */
       meta ? { },
-      /*
-         `stdenv.mkDerivation`'s `passthru` argument.
-
-         Type: AttrSet
-      */
       passthru ? { },
-      /*
-         The `checkPhase` to run. Defaults to `shellcheck` on supported
-         platforms and `bash -n`.
-
-         The script path will be given as `$target` in the `checkPhase`.
-
-         Type: String
-      */
       checkPhase ? null,
-      /*
-         Checks to exclude when running `shellcheck`, e.g. `[ "SC2016" ]`.
-
-         See <https://www.shellcheck.net/wiki/> for a list of checks.
-
-         Type: [String]
-      */
       excludeShellChecks ? [ ],
-      /*
-         Extra command-line flags to pass to ShellCheck.
-
-         Type: [String]
-      */
       extraShellCheckFlags ? [ ],
-      /*
-         Bash options to activate with `set -o` at the start of the script.
-
-         Defaults to `[ "errexit" "nounset" "pipefail" ]`.
-
-         Type: [String]
-      */
       bashOptions ? [
         "errexit"
         "nounset"
         "pipefail"
       ],
-      /*
-        Extra arguments to pass to `stdenv.mkDerivation`.
-
-        :::{.caution}
-        Certain derivation attributes are used internally,
-        overriding those could cause problems.
-        :::
-
-        Type: AttrSet
-      */
       derivationArgs ? { },
-      /*
-         Whether to inherit the current `$PATH` in the script.
-
-         Type: Bool
-      */
       inheritPath ? true,
     }@args:
     writeTextFile {