Improved documentation

app.go

@@ -6,6 +6,8 @@ import (
 	"os"
 )
 
+// App is the main structure of a cli application. It is recomended that
+// and app be created with the cli.NewApp() function
 type App struct {
 	// The name of the program. Defaults to os.Args[0]
 	Name string
@@ -21,6 +23,7 @@ type App struct {
 	Action func(context *Context)
 }
 
+// Creates a new cli Application with some reasonable defaults for Name, Usage, Version and Action.
 func NewApp() *App {
 	return &App{
 		Name:    os.Args[0],
@@ -30,6 +33,7 @@ func NewApp() *App {
 	}
 }
 
+// Entry point to the cli app. Parses the arguments slice and routes to the proper flag/args combination
 func (a *App) Run(arguments []string) {
 	// append help to commands
 	if a.Command(helpCommand.Name) == nil {
@@ -70,6 +74,7 @@ func (a *App) Run(arguments []string) {
 	a.Action(context)
 }
 
+// Returns the named command on App. Returns nil if the command does not exist
 func (a *App) Command(name string) *Command {
 	for _, c := range a.Commands {
 		if c.HasName(name) {

command.go

@@ -7,15 +7,23 @@ import (
 	"strings"
 )
 
+// Command is a subcommand for a cli.App.
 type Command struct {
-	Name        string
-	ShortName   string
-	Usage       string
+	// The name of the command
+	Name string
+	// short name of the command. Typically one character
+	ShortName string
+	// A short description of the usage of this command
+	Usage string
+	// A longer explaination of how the command works
 	Description string
-	Action      func(context *Context)
-	Flags       []Flag
+	// The function to call when this command is invoked
+	Action func(context *Context)
+	// List of flags to parse
+	Flags []Flag
 }
 
+// Invokes the command given the context, parses ctx.Args() to generate command-specific flags
 func (c Command) Run(ctx *Context) {
 	// append help to flags
 	c.Flags = append(
@@ -55,6 +63,7 @@ func (c Command) Run(ctx *Context) {
 	c.Action(context)
 }
 
+// Returns true if Command.Name or Command.ShortName matches given name
 func (c Command) HasName(name string) bool {
 	return c.Name == name || c.ShortName == name
 }

context.go

@@ -15,6 +15,7 @@ type Context struct {
 	globalSet *flag.FlagSet
 }
 
+// Creates a new context. For use in when invoking an App or Command action.
 func NewContext(app *App, set *flag.FlagSet, globalSet *flag.FlagSet) *Context {
 	return &Context{app, set, globalSet}
 }
@@ -69,6 +70,7 @@ func (c *Context) GlobalIntSlice(name string) []int {
 	return c.lookupIntSlice(name, c.globalSet)
 }
 
+// Returns the command line arguments associated with the context.
 func (c *Context) Args() []string {
 	return c.flagSet.Args()
 }

flag.go

@@ -4,8 +4,12 @@ import "fmt"
 import "flag"
 import "strconv"
 
+// Flag is a common interface related to parsing flags in cli.
+// For more advanced flag parsing techniques, it is recomended that
+// this interface be implemented.
 type Flag interface {
 	fmt.Stringer
+	// Apply Flag settings to the given flag set
 	Apply(*flag.FlagSet)
 }
 

flag_test.go

@@ -45,7 +45,6 @@ func TestStringFlagHelpOutput(t *testing.T) {
 	}
 }
 
-
 var intFlagTests = []struct {
 	name     string
 	expected string
@@ -64,4 +63,4 @@ func TestIntFlagHelpOutput(t *testing.T) {
 			t.Errorf("%s does not match %s", output, test.expected)
 		}
 	}
-}
+}