Update doc.go and examples

Author: mfridman

doc.go

@@ -1,8 +1,36 @@
-// Package cli provides a lightweight framework for building command-line applications. It features
-// nested subcommand support and flexible flag parsing.
+// Package cli provides a lightweight framework for building command-line applications using Go's
+// standard library flag package. It extends flag functionality to support flags anywhere in command
+// arguments.
 //
-// The package prioritizes simplicity and ease of use, making it an ideal foundation for CLI
-// applications that don't require the overhead of larger frameworks. This focused design allows
-// developers to concentrate on their application's core functionality while keeping their code
-// simple and maintainable.
+// Key features:
+//   - Nested subcommands for organizing complex CLIs
+//   - Flexible flag parsing, allowing flags anywhere in arguments
+//   - Parent-to-child flag inheritance
+//   - Type-safe flag access
+//   - Automatic help text generation
+//   - Command suggestions for misspelled inputs
+//
+// Quick example:
+//
+//	root := &cli.Command{
+//	    Name:      "echo",
+//	    Usage:     "echo [flags] <text>...",
+//	    ShortHelp: "prints the provided text",
+//	    Flags: cli.FlagsFunc(func(f *flag.FlagSet) {
+//	        f.Bool("c", false, "capitalize the input")
+//	    }),
+//	    Exec: func(ctx context.Context, s *cli.State) error {
+//	        output := strings.Join(s.Args, " ")
+//	        if cli.GetFlag[bool](s, "c") {
+//	            output = strings.ToUpper(output)
+//	        }
+//	        fmt.Fprintln(s.Stdout, output)
+//	        return nil
+//	    },
+//	}
+//
+// The package intentionally maintains a minimal API surface to serve as a building block for CLI
+// applications while leveraging the standard library's flag package. This approach enables
+// developers to build maintainable command-line tools quickly while focusing on application logic
+// rather than framework complexity.
 package cli

examples/cmd/task/main.go

@@ -25,7 +25,7 @@ import (
 // 		├── add <text>
 // 		│   └── (-tags)
 // 		├── done <id>
-// 		└── remove <id>
+// 		└── remove <id> (-force, -all)
 
 func main() {
 	root := &cli.Command{

examples/cmd/task/tasks.go

@@ -46,13 +46,14 @@ func (l *TaskList) Add(t Task) {
 	l.Tasks = append(l.Tasks, t)
 }
 
-func (l *TaskList) Remove(id int) {
+func (l *TaskList) Remove(id int) error {
 	for i, t := range l.Tasks {
 		if t.ID == id {
 			l.Tasks = append(l.Tasks[:i], l.Tasks[i+1:]...)
-			return
+			return nil
 		}
 	}
+	return fmt.Errorf("task with ID %d not found", id)
 }
 
 func (l *TaskList) List() []Task {