mcfg: update docs

mcfg/cli.go

@@ -26,11 +26,10 @@ type cliTail struct {
 }
 
 // WithCLITail returns a Context which modifies the behavior of SourceCLI's
-// Parse, if SourceCLI is used with that Context at all. Normally when SourceCLI
+// Parse. Normally when SourceCLI encounters an unexpected Arg it will
-// encounters an unexpected Arg it will immediately return an error. This
+// immediately return an error. This function modifies the Context to indicate
-// function modifies the Context to indicate to Parse that the unexpected Arg,
+// to Parse that the unexpected Arg, and all subsequent Args (i.e. the tail),
-// and all subsequent Args (i.e. the tail) should be set to the returned
+// should be set to the returned []string value.
-// []string value.
 //
 // The descr (optional) will be appended to the "Usage" line which is printed
 // with the help document when "-h" is passed in.

mcfg/cli_test.go

@@ -304,9 +304,12 @@ func TestWithCLISubCommand(t *T) {
 }
 
 func ExampleWithCLISubCommand() {
+	// Create a new Context with a parameter "foo", which can be used across all
+	// sub-commands.
 	ctx := context.Background()
 	ctx, foo := WithInt(ctx, "foo", 0, "Description of foo.")
 
+	// Create a sub-command "a", which has a parameter "bar" specific to it.
 	var bar *int
 	ctx, aFlag := WithCLISubCommand(ctx, "a", "Description of a.",
 		func(ctx context.Context) context.Context {
@@ -314,6 +317,7 @@ func ExampleWithCLISubCommand() {
 			return ctx
 		})
 
+	// Create a sub-command "b", which has a parameter "baz" specific to it.
 	var baz *int
 	ctx, bFlag := WithCLISubCommand(ctx, "b", "Description of b.",
 		func(ctx context.Context) context.Context {
@@ -321,13 +325,15 @@ func ExampleWithCLISubCommand() {
 			return ctx
 		})
 
+	// Use Populate with manually generated CLI arguments, calling the "a"
+	// sub-command.
 	args := []string{"a", "--foo=1", "--bar=2"}
 	if _, err := Populate(ctx, &SourceCLI{Args: args}); err != nil {
 		panic(err)
 	}
 	fmt.Printf("foo:%d bar:%d aFlag:%v bFlag:%v\n", *foo, *bar, *aFlag, *bFlag)
 
-	// reset output for another Populate
+	// reset output for another Populate, this time calling the "b" sub-command.
 	*aFlag = false
 	args = []string{"b", "--foo=1", "--baz=3"}
 	if _, err := Populate(ctx, &SourceCLI{Args: args}); err != nil {

mcfg/mcfg.go

@@ -1,5 +1,12 @@
-// Package mcfg provides a simple foundation for complex service/binary
+// Package mcfg implements the creation of different types of configuration
-// configuration, initialization, and destruction
+// parameters and various methods of filling those parameters from external
+// configuration sources (e.g. the command line and environment variables).
+//
+// Parameters are registered onto a context, and that same context is used later
+// to collect and fulfill those parameters. When used with the mctx package's
+// child/parent context functionality, the path of a context is incorporated
+// into the parameter's full name in order to namespace parameters which exist
+// in different contexts.
 package mcfg
 
 import (
@@ -45,9 +52,9 @@ func sortParams(params []Param) {
 	})
 }
 
-// CollectParams returns all Params gathered by recursively retrieving them from
+// CollectParams gathers all Params by recursively retrieving them from this
-// this Context and its children. Returned Params are sorted according to their
+// Context and its children. Returned Params are sorted according to their Path
-// Path and Name.
+// and Name.
 func CollectParams(ctx context.Context) []Param {
 	var params []Param