build-support/docker/default.nix: Refer to docs and tests

This removes redundant inline docs, because
- users should consult the better docs in the manual,
- contributors should add to the manual, not the inline comments

pkgs/build-support/docker/default.nix

@@ -1129,26 +1129,18 @@ rec {
   );
 
   # This function streams a docker image that behaves like a nix-shell for a derivation
+  # Docs: doc/build-helpers/images/dockertools.section.md
+  # Tests: nixos/tests/docker-tools-nix-shell.nix
   streamNixShellImage =
-    { # The derivation whose environment this docker image should be based on
+    { drv
-      drv
+    , name ? drv.name + "-env"
-    , # Image Name
+    , tag ? null
-      name ? drv.name + "-env"
+    , uid ? 1000
-    , # Image tag, the Nix's output hash will be used if null
+    , gid ? 1000
-      tag ? null
+    , homeDirectory ? "/build"
-    , # User id to run the container as. Defaults to 1000, because many
+    , shell ? bashInteractive + "/bin/bash"
-      # binaries don't like to be run as root
+    , command ? null
-      uid ? 1000
+    , run ? null
-    , # Group id to run the container as, see also uid
-      gid ? 1000
-    , # The home directory of the user
-      homeDirectory ? "/build"
-    , # The path to the bash binary to use as the shell. See `NIX_BUILD_SHELL` in `man nix-shell`
-      shell ? bashInteractive + "/bin/bash"
-    , # Run this command in the environment of the derivation, in an interactive shell. See `--command` in `man nix-shell`
-      command ? null
-    , # Same as `command`, but runs the command in a non-interactive shell instead. See `--run` in `man nix-shell`
-      run ? null
     }:
       assert lib.assertMsg (! (drv.drvAttrs.__structuredAttrs or false))
         "streamNixShellImage: Does not work with the derivation ${drv.name} because it uses __structuredAttrs";
@@ -1284,6 +1276,8 @@ rec {
       };
 
   # Wrapper around streamNixShellImage to build an image from the result
+  # Docs: doc/build-helpers/images/dockertools.section.md
+  # Tests: nixos/tests/docker-tools-nix-shell.nix
   buildNixShellImage = { drv, compressor ? "gz", ... }@args:
     let
       stream = streamNixShellImage (builtins.removeAttrs args ["compressor"]);