dockerTools: Comment tidy-ups, and documentation update (#450384)

doc/build-helpers/images/dockertools.section.md

@@ -1,6 +1,6 @@
 # pkgs.dockerTools {#sec-pkgs-dockerTools}
 
-`pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions).
+`pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [Docker Image Specification v1.3.1](https://github.com/moby/docker-image-spec/blob/v1.3.1/spec.md).
 Docker itself is not used to perform any of the operations done by these functions.
 
 ## buildImage {#ssec-pkgs-dockerTools-buildImage}
@@ -130,7 +130,7 @@ Similarly, if you encounter errors similar to `Error_Protocol ("certificate has
 `config` (Attribute Set or Null; _optional_)
 
 : Used to specify the configuration of the containers that will be started off the generated image.
-  Must be an attribute set, with each attribute as listed in the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions).
+  Must be an attribute set, with each attribute as listed in the [Docker Image Specification v1.3.1](https://github.com/moby/docker-image-spec/blob/v1.3.1/spec.md#image-json-field-descriptions).
 
   _Default value:_ `null`.
 
@@ -138,7 +138,7 @@ Similarly, if you encounter errors similar to `Error_Protocol ("certificate has
 
 : Used to specify the image architecture.
   This is useful for multi-architecture builds that don't need cross compiling.
-  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/config.md#properties), which should still be compatible with Docker.
   According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.
 
   _Default value:_ the same value from `pkgs.go.GOARCH`.

pkgs/build-support/docker/default.nix

@@ -1241,7 +1241,8 @@ rec {
     result
   );
 
-  # This function streams a docker image that behaves like a nix-shell for a derivation
+  # 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 =
@@ -1251,6 +1252,9 @@ rec {
       tag ? null,
       uid ? 1000,
       gid ? 1000,
+      # Default to `/build` instead of a non-existent `/homeless-shelter` for backwards compatibility.
+      #
+      # https://github.com/NixOS/nix/issues/6379
       homeDirectory ? "/build",
       shell ? bashInteractive + "/bin/bash",
       command ? null,
@@ -1357,10 +1361,14 @@ rec {
         binSh
         usrBinEnv
         (fakeNss.override {
-          # Allows programs to look up the build user's home directory
+          # Allows programs to look up the build user's home directory.
+          #
           # https://github.com/NixOS/nix/blob/2.32.0/src/libstore/unix/build/linux-derivation-builder.cc#L409-L416
-          # Slightly differs however: We use the passed-in homeDirectory instead of sandboxBuildDir.
+          #
-          # We're doing this because it's arguably a bug in Nix that sandboxBuildDir is used here: https://github.com/NixOS/nix/issues/6379
+          # This slightly differs, however, since we use the passed-in `homeDirectory` instead of `sandboxBuildDir`.
+          # We're doing this because it is arguably a bug in Nix that `sandboxBuildDir` is used here.
+          #
+          # https://github.com/NixOS/nix/issues/6379
           extraPasswdLines = [
             "nixbld:x:${toString uid}:${toString gid}:Build user:${homeDirectory}:/noshell"
           ];
@@ -1373,12 +1381,11 @@ rec {
       fakeRootCommands = ''
         # Effectively a single-user installation of Nix, giving the user full
         # control over the Nix store. Needed for building the derivation this
-        # shell is for, but also in case one wants to use Nix inside the
+        # shell is for, but also in case one wants to use Nix inside the image.
-        # image
         mkdir -p ./nix/{store,var/nix} ./etc/nix
         chown -R ${toString uid}:${toString gid} ./nix ./etc/nix
 
-        # Gives the user control over the build directory
+        # Gives the user control over the build directory.
         mkdir -p .${sandboxBuildDir}
         chown -R ${toString uid}:${toString gid} .${sandboxBuildDir}
       '';
@@ -1403,7 +1410,8 @@ rec {
       config.Env = lib.mapAttrsToList (name: value: "${name}=${value}") envVars;
     };
 
-  # Wrapper around streamNixShellImage to build an image from the result
+  # 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 =