Document invocation reporting contracts

identity.go

@@ -18,8 +18,11 @@ type Identity struct {
 	Revision string
 }
 
-// Streams contains the output destinations associated with a command
-// invocation.
+// Streams contains the caller-owned output destinations associated with an
+// invocation. Out receives substantive results; Err receives messages,
+// terminal explanations, usage guidance, and CommandKit diagnostics. Nil
+// destinations are replaced with io.Discard. CommandKit does not close or flush
+// supplied writers.
 type Streams struct {
 	// Out receives help and command reports.
 	Out io.Writer
@@ -37,10 +40,11 @@ func normalizeStreams(streams Streams) Streams {
 	return streams
 }
 
-// Invocation provides execution context and reporting to a command handler.
-// For command aliases, EnteredPath and CanonicalPath expose the route the
-// caller used and the selected canonical command path. Both omit the
-// executable name, flags, and operands.
+// Invocation provides execution context and invocation-scoped reporting to a
+// command handler. Execute finalizes its reporter before returning. For command
+// aliases, EnteredPath and CanonicalPath expose the route the caller used and
+// the selected canonical command path. Both omit the executable name, flags,
+// and operands.
 type Invocation struct {
 	// Context carries caller cancellation and request-scoped values.
 	Context context.Context
@@ -50,7 +54,8 @@ type Invocation struct {
 	canonicalPath string
 }
 
-// Reporter returns the reporting facility for this invocation.
+// Reporter returns the reporting facility supplied for this invocation. A
+// manually constructed Invocation has no reporter.
 func (inv Invocation) Reporter() *Reporter { return inv.reporter }
 
 // EnteredPath returns the command path used to invoke the selected command,