command: use NUL for magic usage string

This change also improves documentation.

Signed-off-by: Ophestra <cat@gensokyo.uk>

1 files changed, 26 insertions, 6 deletions

diff --git a/command/command.go b/command/command.go
index 5533c4ef..f3b699bc 100644
--- a/command/command.go
+++ b/command/command.go
@@ -6,36 +6,43 @@ import (
 	"strings"
 )
 
-// UsageInternal causes the command to be hidden from help text when set as the usage string.
-const UsageInternal = "internal"
+// UsageInternal is a special usage string that hides the command from the
+// generated help message.
+const UsageInternal = "\x00"
 
 type (
 	// HandlerFunc is called when matching a directly handled subcommand tree.
 	HandlerFunc = func(args []string) error
 
-	// LogFunc is the function signature of a printf function.
+	// LogFunc is the function signature of a printf function. The zero value
+	// implies [log.Printf].
 	LogFunc = func(format string, a ...any)
 
-	// FlagDefiner is a deferred flag definer value, usually encapsulating the default value.
+	// FlagDefiner is a deferred flag definer value, usually encapsulating the
+	// default value.
 	FlagDefiner interface {
 		// Define defines the flag in set.
 		Define(b *strings.Builder, set *flag.FlagSet, p any, name, usage string)
 	}
 
+	// A Flag is satisfied by command objects capable of receiving flags.
 	Flag[T any] interface {
 		// Flag defines a generic flag type in Node's flag set.
 		Flag(p any, name string, value FlagDefiner, usage string) T
 	}
 
+	// A Command is the root of a command tree.
 	Command interface {
 		Parse(arguments []string) error
 
-		// MustParse determines exit outcomes for Parse errors
-		// and calls handleError if [HandlerFunc] returns a non-nil error.
+		// MustParse determines exit outcomes for Parse errors and calls
+		// handleError if [HandlerFunc] returns a non-nil error.
 		MustParse(arguments []string, handleError func(error))
 
 		baseNode[Command]
 	}
+
+	// A Node is a subcommand under a [Command].
 	Node baseNode[Node]
 
 	baseNode[T any] interface {
@@ -53,3 +60,16 @@ type (
 		Flag[T]
 	}
 )
+
+// rootNode satisfies baseNode for [Command].
+type rootNode struct{ *node }
+
+func (r rootNode) Command(name, usage string, f HandlerFunc) Command {
+	r.node.Command(name, usage, f)
+	return r
+}
+
+func (r rootNode) Flag(p any, name string, value FlagDefiner, usage string) Command {
+	r.node.Flag(p, name, value, usage)
+	return r
+}