Improve comments in images

images/base-notebook/Dockerfile

@@ -13,16 +13,18 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 
 USER root
 
-# Install all OS dependencies for the Server that starts but lacks all
-# features (e.g., download as all possible file formats)
+# Install all OS dependencies for the Server that starts
+# but lacks all features (e.g., download as all possible file formats)
 RUN apt-get update --yes && \
     apt-get install --yes --no-install-recommends \
+    # - Add necessary fonts for matplotlib/seaborn
+    #   See https://github.com/jupyter/docker-stacks/pull/380 for details
     fonts-liberation \
-    # - pandoc is used to convert notebooks to html files
+    # - `pandoc` is used to convert notebooks to html files
     #   it's not present in the aarch64 Ubuntu image, so we install it here
     pandoc \
-    # - run-one - a wrapper script that runs no more
-    #   than one unique  instance  of  some  command with a unique set of arguments,
+    # - `run-one` - a wrapper script that runs no more
+    #   than one unique instance of some command with a unique set of arguments,
     #   we use `run-one-constantly` to support the `RESTARTABLE` option
     run-one && \
     apt-get clean && rm -rf /var/lib/apt/lists/*

images/docker-stacks-foundation/Dockerfile

@@ -22,8 +22,8 @@ USER root
 # but lacks all features (e.g., download as all possible file formats)
 ENV DEBIAN_FRONTEND noninteractive
 RUN apt-get update --yes && \
-    # - `apt-get upgrade` is run to patch known vulnerabilities in apt-get packages as
-    #   the Ubuntu base image is rebuilt too seldom sometimes (less than once a month)
+    # - `apt-get upgrade` is run to patch known vulnerabilities in system packages
+    #   as the Ubuntu base image is rebuilt too seldom sometimes (less than once a month)
     apt-get upgrade --yes && \
     apt-get install --yes --no-install-recommends \
     # - bzip2 is necessary to extract the micromamba executable.
@@ -31,9 +31,9 @@ RUN apt-get update --yes && \
     ca-certificates \
     locales \
     sudo \
-    # - tini is installed as a helpful container entrypoint that reaps zombie
-    #   processes and such of the actual executable we want to start, see
-    #   https://github.com/krallin/tini#why-tini for details.
+    # - `tini` is installed as a helpful container entrypoint,
+    #   that reaps zombie processes and such of the actual executable we want to start
+    #   See https://github.com/krallin/tini#why-tini for details
     tini \
     wget && \
     apt-get clean && rm -rf /var/lib/apt/lists/* && \
@@ -102,6 +102,7 @@ RUN set -x && \
         # Should be simpler, see <https://github.com/mamba-org/mamba/issues/1437>
         arch="64"; \
     fi && \
+    # https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html#linux-and-macos
     wget --progress=dot:giga -O - \
         "https://micro.mamba.pm/api/micromamba/linux-${arch}/latest" | tar -xvj bin/micromamba && \
     PYTHON_SPECIFIER="python=${PYTHON_VERSION}" && \

images/minimal-notebook/Dockerfile

@@ -25,10 +25,10 @@ RUN apt-get update --yes && \
     vim-tiny \
     # git-over-ssh
     openssh-client \
-    # less is needed to run help in R
+    # `less` is needed to run help in R
     # see: https://github.com/jupyter/docker-stacks/issues/1588
     less \
-    # nbconvert dependencies
+    # `nbconvert` dependencies
     # https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex
     texlive-xetex \
     texlive-fonts-recommended \

images/pyspark-notebook/ipython_kernel_config.py

@@ -7,8 +7,7 @@
 # Logs are particularly verbose with Spark, that is why we turn them off through this flag.
 # <https://github.com/jupyter/docker-stacks/issues/1423>
 
-# Attempt to capture and forward low-level output, e.g. produced by Extension
-#  libraries.
-#  Default: True
+# Attempt to capture and forward low-level output, e.g. produced by Extension libraries.
+# Default: True
 # type:ignore
 c.IPKernelApp.capture_fd_output = False  # noqa: F821