From 12bc0136e1433cb5de29ea050a5bc2d0e7ce30ef Mon Sep 17 00:00:00 2001
From: Steven Allen <steven@stebalien.com>
Date: Sat, 4 Apr 2020 14:00:43 -0700
Subject: [PATCH] doc: document command fields

---
 command.go | 43 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/command.go b/command.go
index d39a5e6..b4a1199 100644
--- a/command.go
+++ b/command.go
@@ -32,17 +32,40 @@ type PostRunMap map[PostRunType]func(Response, ResponseEmitter) error
 // Command is a runnable command, with input arguments and options (flags).
 // It can also have Subcommands, to group units of work into sets.
 type Command struct {
-	Options   []Option
+	// Options defines the flags accepted by the command. Flags on specified
+	// on parent commands are inherited by sub commands.
+	Options []Option
+
+	// Arguments defines the positional arguments for the command. These
+	// arguments can be strings and/or files.
+	//
+	// The rules for valid arguments are as follows:
+	//
+	// 1. No required arguments may follow optional arguments.
+	// 2. There can be at most one STDIN argument.
+	// 3. There can be at most one variadic argument, and it must be last.
 	Arguments []Argument
-	PreRun    func(req *Request, env Environment) error
+
+	// PreRun is run before Run. When executing a command on a remote
+	// daemon, PreRun is always run in the local process.
+	PreRun func(req *Request, env Environment) error
 
 	// Run is the function that processes the request to generate a response.
 	// Note that when executing the command over the HTTP API you can only read
 	// after writing when using multipart requests. The request body will not be
 	// available for reading after the HTTP connection has been written to.
-	Run      Function
-	PostRun  PostRunMap
+	Run Function
+
+	// PostRun is run after Run, and can transform results returned by run.
+	// When executing a command on a remote daemon, PostRun is always run in
+	// the local process.
+	PostRun PostRunMap
+
+	// Encoders encode results from Run (and/or PostRun) in the desired
+	// encoding.
 	Encoders EncoderMap
+
+	// Helptext is the command's help text.
 	Helptext HelpText
 
 	// External denotes that a command is actually an external binary.
@@ -54,7 +77,17 @@ type Command struct {
 	// the Run Function.
 	//
 	// ie. If command Run returns &Block{}, then Command.Type == &Block{}
-	Type        interface{}
+	Type interface{}
+
+	// Subcommands allow attaching sub commands to a command.
+	//
+	// Note: A command can specify both a Run function and Subcommands. If
+	// invoked with no arguments, or an argument that matches no
+	// sub commands, the Run function of the current command will be invoked.
+	//
+	// Take care when specifying both a Run function and Subcommands. A
+	// simple typo in a sub command will invoke the parent command and may
+	// end up returning a cryptic error to the user.
 	Subcommands map[string]*Command
 }
 
-- 
GitLab