aboutsummaryrefslogtreecommitdiffstats
path: root/doc.go
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-12-27 18:26:05 -0500
committerEugene Triguba <hello@eugenetriguba.com>2025-12-27 18:26:05 -0500
commitb8b9d64012f07a48cf97394805a3368287ff41f2 (patch)
tree8c5b94657e7f58366f93dfda5c4b79de487ed6a3 /doc.go
parentRelease v0.5.0 (diff)
downloadsubcmd-b8b9d64012f07a48cf97394805a3368287ff41f2.zip
Clarify godoc comments and provide more examples
Diffstat (limited to 'doc.go')
-rw-r--r--doc.go54
1 files changed, 41 insertions, 13 deletions
diff --git a/doc.go b/doc.go
index d38be35..0e38488 100644
--- a/doc.go
+++ b/doc.go
@@ -1,5 +1,5 @@
// Package subcmd provides a simple and flexible subcommand framework built on
-// top of the standard library's flag package.
+// top of the standard library's [flag] package.
//
// This package makes it easy to build command-line applications with multiple
// subcommands, similar to tools like git, docker, or kubectl. Each subcommand
@@ -7,9 +7,19 @@
//
// # Basic Usage
//
-// To use subcmd, implement the Command interface for each subcommand and
-// register them with a Registry. The framework handles parsing, flag management,
-// and command execution.
+// To use subcmd, implement the [subcmd.Command] interface for each subcommand and
+// [subcmd.Register] them. The library handles parsing, flag management, and command
+// execution.
+//
+// package main
+//
+// import (
+// "context"
+// "flag"
+// "fmt"
+// "git.sr.ht/~eugenetriguba/subcmd"
+// "os"
+// )
//
// type greetCmd struct {
// name string
@@ -22,11 +32,9 @@
// Prints a greeting message.
// `
// }
-//
// func (g *greetCmd) SetFlags(f *flag.FlagSet) {
// f.StringVar(&g.name, "name", "World", "name to greet")
// }
-//
// func (g *greetCmd) Execute(ctx context.Context, f *flag.FlagSet, args ...any) subcmd.ExitStatus {
// fmt.Printf("Hello, %s!\n", g.name)
// return subcmd.ExitSuccess
@@ -38,6 +46,23 @@
// os.Exit(int(subcmd.Execute(context.Background())))
// }
//
+// We'll see the following output when we run our new CLI:
+//
+// $ go build -o main
+// $ ./main
+// Usage: ./main <flags> <subcommand> <subcommand args>
+//
+// Subcommands:
+// greet greet a person
+// help describe subcommands and their syntax
+//
+// $ ./main help greet
+// greet -name <name>:
+// Prints a greeting message.
+//
+// $ ./main greet -name eugene
+// Hello, eugene!
+//
// # Command Groups
//
// Commands can be organized into groups for better help output:
@@ -50,15 +75,18 @@
//
// The package provides several built-in commands:
//
-// - HelpCommand() - Display help for all commands or a specific command
-// - ManHelpCommand(prefix) - Open man pages for commands (e.g., "myapp" and "myapp-subcommand")
-// - CommandsCommand() - List all available command names
-// - FlagsCommand() - List all top-level flags
+// - [subcmd.HelpCommand]
+// - [subcmd.ManHelpCommand]
+// - [subcmd.CommandsCommand]
+// - [subcmd.FlagsCommand]
//
// # Registry
//
-// While the package provides a default registry for convenience, you can
-// create custom registries for more control:
+// Many top-level functions, like [subcmd.Register], operate on a
+// global default package-level registry. This makes it easier to
+// use the library in the common case.
+//
+// However, you can create custom registries for more control:
//
// registry := subcmd.NewRegistry(subcmd.WithOutput(customWriter))
// registry.Register(&myCmd{}, "")
@@ -70,7 +98,7 @@
// # Top-level Flags
//
// To add top-level flags (flags that apply before the subcommand), use the
-// Flags() accessor:
+// [subcmd.Flags] accessor:
//
// verbose := subcmd.Flags().Bool("v", false, "verbose output")
// subcmd.Register(&myCmd{}, "")