better help

Author: kurowski

local/etc/uceap.d/devcontainer_on_create.sh

@@ -54,6 +54,11 @@ function devcontainer_on_create() {
 	fi
 }
 
-_devcontainer_on_create_desc="Runs when the devcontainer is created"
-_devcontainer_on_create_help="
-"
+_devcontainer_on_create_desc='Runs when the devcontainer is created'
+_devcontainer_on_create_help='
+This command implements the `onCreateCommand` lifecycle event for dev containers.
+
+This command is the first of three (along with `updateContentCommand` and `postCreateCommand`) that finalizes container setup when a dev container is created. It and subsequent commands execute **inside** the container immediately after it has started for the first time.
+
+Cloud services can use this command when caching or prebuilding a container. This means that it will not typically have access to user-scoped assets or secrets.
+'

local/etc/uceap.d/devcontainer_post_create.sh

@@ -34,6 +34,11 @@ function devcontainer_post_create() {
 	fi
 }
 
-_devcontainer_post_create_desc="Runs after the devcontainer is created"
-_devcontainer_post_create_help="
-"
+_devcontainer_post_create_desc='Runs after the devcontainer is created'
+_devcontainer_post_create_help='
+This command implements the `postCreateCommand` lifecycle event for dev containers.
+
+This is the last of three that finalizes container setup when a dev container is created. It happens after `updateContentCommand` and once the dev container has been assigned to a user for the first time.
+
+Cloud services can use this command to take advantage of user specific secrets and permissions.
+'

local/etc/uceap.d/devcontainer_post_start.sh

@@ -8,6 +8,9 @@ function devcontainer_post_start() {
 	fi
 }
 
-_devcontainer_post_start_desc="Runs after the devcontainer is started"
-_devcontainer_post_start_help="
-"
+_devcontainer_post_start_desc='Runs after the devcontainer is started'
+_devcontainer_post_start_help='
+This command implements the `postStartCommand` lifecycle event for dev containers.
+
+This is run each time the container is successfully started.
+'

local/etc/uceap.d/devcontainer_update_content.sh

@@ -16,6 +16,11 @@ function devcontainer_update_content() {
 	fi
 }
 
-_devcontainer_update_content_desc="Runs when the devcontainer needs to update content"
-_devcontainer_update_content_help="
-"
+_devcontainer_update_content_desc='Runs when the devcontainer needs to update content'
+_devcontainer_update_content_help='
+This command implements the `updateContentCommand` lifecycle event for dev containers.
+
+This is the second of three that finalizes container setup when a dev container is created. It executes inside the container after `onCreateCommand` whenever new content is available in the source tree during the creation process.
+
+It will execute at least once, but cloud services will also periodically execute the command to refresh cached or prebuilt containers. Like cloud services using `onCreateCommand`, it can only take advantage of repository and org scoped secrets or permissions.
+'

local/etc/uceap.d/help.sh

@@ -29,6 +29,8 @@ function _help() {
 }
 _help_desc='Displays help for `uceap` commands'
 _help_help='
+Show help for UCEAP CLI commands.
+
 # Usage
 
 ``` sh