Comment tweaks

.devcontainer/cache/build-cache-image.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
-# This file simply wraps the dockeer build command used to build the image with the
-# cached result of the commands from "prepare.sh" and pushes it to the specified
-# container image registry.
+# This file simply wraps the docker build command to build an image that includes
+# a cache.tar file with the result of "prepare.sh" inside of it. See cache.Dockerfile
+# for the steps that are actually taken to do this.
 
 set -e
 

.devcontainer/cache/cache.Dockerfile

@@ -1,7 +1,7 @@
-# This dockerfile is used to build up from a base image to create an image with cached results of running "prepare.sh".
+# This dockerfile is used to build up from a base image to create an image a cache.tar file containing the results of running "prepare.sh".
 # Other image contents: https://github.com/microsoft/vscode-dev-containers/blob/master/repository-containers/images/github.com/microsoft/vscode/.devcontainer/base.Dockerfile
 
-# First stage generates the cache tar
+# This first stage generates cache.tar
 FROM mcr.microsoft.com/vscode/devcontainers/repos/microsoft/vscode:dev as cache
 ARG USERNAME=node
 COPY --chown=${USERNAME}:${USERNAME} . /repo-source-tmp/
@@ -13,7 +13,8 @@ RUN mkdir /usr/local/etc/devcontainer-cache \
 		&& .devcontainer/prepare.sh \
 		&& .devcontainer/cache/cache-diff.sh"
 
-# Second stage is the acual output that includes only the tar - restore-diff.sh is then fired on postCreateCommand to expand it
+# This second stage starts fresh and just copies in cache.tar from the previous stage. The related
+# devcontainer.json file is then setup to have postCreateCommand fire restore-diff.sh to expand it.
 FROM mcr.microsoft.com/vscode/devcontainers/repos/microsoft/vscode:dev as dev-container
 ARG USERNAME=node
 ARG CACHE_FOLDER="/usr/local/etc/devcontainer-cache"

.devcontainer/cache/restore-diff.sh

@@ -1,9 +1,8 @@
 #!/usr/bin/env bash
 
-# This file restores the results of the "prepare.sh" into their proper locations
-# once the container has been created. It runs as a postCreateCommand which
-# in GitHub Codespaces occurs parallel to other startup activities and does not
-# really add to the overal startup time given how quick the operation ends up being.
+# This file expands the cache.tar file in the image that contains the results of "prepare.sh"
+# on top of the source tree. It runs as a postCreateCommand which runs after the container/codespace
+# is already up where you would typically run a command like "yarn install".
 
 set -e
 

.devcontainer/prepare.sh

@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 
-# This file contains the steps that should be run when creating the intermediary image that contains
-# contents for that should be in the image by default. It will be used to build up from the base image
-# to create an image that speeds up first time use of the dev container by "caching" the results
-# of these commands. Developers can still run these commands without an issue once the container is
-# up, but only differences will be processed which also speeds up the first time these operations occur.
+# This file contains the steps that should be run when building a "cache" image with contents that should be
+# layered directly **on top of the source tree** once a dev container is created. This avoids having to run long
+# running commands like "yarn install" from the ground up. Developers (and should) still run these commands
+# after the actual dev container is created, but only differences will be processed.
 
 yarn install
 yarn electron