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

# 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}

`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`.

: 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`.

    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 =

      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,

        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"

          ];

      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

        # image

        # shell is for, but also in case one wants to use Nix inside the 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}

      '';

      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 =