From d522fc3396a1f1cda773dddfe189ff19b739e8cd Mon Sep 17 00:00:00 2001
From: Solomon Hykes <sh.github.6811@hykes.org>
Date: Tue, 6 Apr 2021 20:52:06 +0000
Subject: [PATCH] dev.cue: polish

Signed-off-by: Solomon Hykes <sh.github.6811@hykes.org>
---
 dev.cue    | 15 +++++++++------
 docker.cue | 49 +++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/dev.cue b/dev.cue
index 02f9ec66..675e68fd 100644
--- a/dev.cue
+++ b/dev.cue
@@ -8,6 +8,7 @@ import (
 // Dagger source code
 source: dagger.#Artifact
 
+// Build the dagger binaries
 build: #Container & {
 	image: #ImageFromRef & {ref: "docker.io/golang:1.16-alpine"}
 
@@ -15,6 +16,11 @@ build: #Container & {
 		"apk add --no-cache file",
 	]
 
+	command: """
+		go test -v ./...
+		go build -o /binaries/ ./cmd/...
+		"""
+
 	volume: {
 		daggerSource: {
 			from: source
@@ -36,20 +42,17 @@ build: #Container & {
 
 	dir:       "/src"
 	outputDir: "/binaries"
-	command: """
-		go test -v ./...
-		go build -o /binaries/ ./cmd/...
-		"""
 }
 
+// Execute `dagger help`
 usage: #Container & {
 	image: alpine.#Image
 
+	command: "dagger help"
+
 	volume: binaries: {
 		from: build
 		dest: "/usr/local/dagger/bin/"
 	}
 	shell: search: "/usr/local/dagger/bin": true
-
-	command: "dagger help"
 }
diff --git a/docker.cue b/docker.cue
index a33b8e69..423658c4 100644
--- a/docker.cue
+++ b/docker.cue
@@ -1,3 +1,5 @@
+// docker: build and run Docker containers
+// https://docker.com
 package main
 
 import (
@@ -39,18 +41,48 @@ import (
 	]
 }
 
+// Run a Docker container
 #Container: {
 
+	// Container image
 	image: dagger.#Artifact
 
-	// Optional setup scripts
+	// Independently cacheable setup commands
 	setup: [...string]
 
+	// Command to execute
+	command: string
+
 	// Environment variables shared by all commands
 	env: [string]: string
 
+	// Directory in which the command is executed
+	dir: string | *"/"
+
+	// Directory to expose as the output.
+	// By default the root filesystem is the output.
+	outputDir: string | *"/"
+
+	// If true, the command is never cached.
+	// (false by default).
+	always: true | *false
+
+	// External volumes. There are 4 types:
+	//
+	// 1. "mount": mount any artifact.
+	//     Changes are not included in the final output.
+	//
+	// 2. "copy": copy any artifact.
+	//     Changes are included in the final output.
+	//
+	// 3. "tmpfs": create a temporary directory.
+	//
+	// 4. "cache": create a persistent cache diretory.
+	//
 	volume: [name=string]: {
+		// Destination path
 		dest: string | *"/"
+
 		*{
 			type:   "mount"
 			from:   dagger.#Artifact
@@ -64,9 +96,15 @@ import (
 		}
 	}
 
+	// Configure the shell which executes all commands.
 	shell: {
+		// Path of the shell to execute
 		path: string | *"/bin/sh"
+		// Arguments to pass to the shell prior to the command
 		args: [...string] | *["-c"]
+		// Map of directories to search for commands
+		// In POSIX shells this is used to generate the $PATH
+		// environment variable.
 		search: [string]: bool
 		search: {
 			"/sbin":           true
@@ -79,15 +117,6 @@ import (
 	}
 	env: PATH: string | *strings.Join([ for p, v in shell.search if v {p}], ":")
 
-	command: string
-
-	dir: string | *"/"
-
-	env: [string]: string
-
-	outputDir: string | *"/"
-	always:    true | *false
-
 	#up: [
 		op.#Load & {from: image},
 		// Copy volumes with type=copy