From 18962e3ab70a8e7cefaaf130baca6f1035c60dfb Mon Sep 17 00:00:00 2001
From: georglauterbach <44545919+georglauterbach@users.noreply.github.com>
Date: Sat, 4 May 2024 11:24:05 +0000
Subject: [PATCH] miscellaneous documentation improvements

---
 .devcontainer/Dockerfile        |  6 +++++-
 .devcontainer/devcontainer.json | 18 ++++++++++++++++--
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 50fe22c..49386b7 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -11,7 +11,8 @@
 # We use a custom base image (that itself is based on Ubuntu). The
 # image contains additional helpers and programs that ease working
 # inside a Development Container. The image does *not* contain
-# programs or configuration files that are required to build unCORE!
+# programs or configuration files that you could not install manually
+# by yourself.
 FROM ghcr.io/georglauterbach/dev-container-base:1.0.0
 
 SHELL [ "/bin/bash", "-eE", "-u", "-o", "pipefail", "-c" ]
@@ -110,4 +111,7 @@ ENV RUSTUP_HOME="${DEV_CONTAINER_FILES_DIR}/rustup_home"
 # where we will work.
 WORKDIR "${WORKSPACE_DIR}"
 
+# We do not need not do we want to be `root`. The Development Containers
+# standard translates the UID of the host user so that no file conflicts
+# arise.
 USER ubuntu
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 2e5ccd7..c034da6 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -1,5 +1,9 @@
-// ref: https://code.visualstudio.com/docs/devcontainers/create-dev-container
-// ref: https://containers.dev/implementors/json_schema/
+// general::ref: https://code.visualstudio.com/docs/devcontainers/containers
+// creation::ref: https://code.visualstudio.com/docs/devcontainers/create-dev-container
+// json_schema::ref: https://containers.dev/implementors/json_schema/
+// variables::ref:
+//   https://github.com/microsoft/vscode-remote-release/issues/2697#issuecomment-609854675
+//   https://containers.dev/implementors/json_reference/#variables-in-devcontainerjson
 {
   "name": "unCORE",
   "build": {
@@ -15,6 +19,11 @@
       // workspace.
       "WORKSPACE_DIR_ARG": "${containerWorkspaceFolder}"
     },
+    "options": [
+      // Having plain output while building, and not the collapsed BuildKit output,
+      // makes finding problems easier.
+      "--progress=plain"
+    ]
   },
   "updateRemoteUserUID": true,
   "remoteUser": "ubuntu",
@@ -53,6 +62,11 @@
         "files.exclude": {
           "**/.git": true
         },
+        "files.watcherExclude": {
+          "**/.git/objects/": true,
+          "code/target": true,
+          "code/.dev_container/": true
+        },
         // ? extensions
         // * extensions::docsView
         "docsView.documentationView.updateMode": "sticky",