Improve examples in docs

commands.go

@@ -15,6 +15,15 @@ import (
 // the entire specified duration. For example, if we're ticking for one minute
 // and the clock is at 12:34:20 then the next tick will happen at 12:35:00, 40
 // seconds later.
+//
+// To produce the command, pass a duration and a fnuction which returns
+// a message containing the time at which the tick occurred.
+//
+//   type TickMsg time.Time
+//
+//   cmd := Every(time.Second, func(t time.Time) Msg {
+//      return TickMsg(t)
+//   })
 func Every(duration time.Duration, fn func(time.Time) Msg) Cmd {
 	return func() Msg {
 		n := time.Now()
@@ -24,9 +33,18 @@ func Every(duration time.Duration, fn func(time.Time) Msg) Cmd {
 	}
 }
 
-// Tick is a command that at an interval independent of the system clock at the
-// given duration. That is, the timer begins when precisely when invoked, and
-// runs for its entire duration.
+// Tick produces a command that at an interval independent of the system clock
+// at the given duration. That is, the timer begins when precisely when
+// invoked, and runs for its entire duration.
+//
+// To produce the command, pass a duration and a fnuction which returns
+// a message containing the time at which the tick occurred.
+//
+//   type TickMsg time.Time
+//
+//   cmd := Tick(time.Second, func(t time.Time) Msg {
+//      return TickMsg(t)
+//   })
 func Tick(d time.Duration, fn func(time.Time) Msg) Cmd {
 	return func() Msg {
 		t := time.NewTimer(d)

key.go

@@ -11,19 +11,28 @@ import (
 // the program's update function. There are a couple general patterns you could
 // use to check for keypresses:
 //
+//     // Switch on the type (safer)
 //     switch msg := msg.(type) {
 //     case KeyMsg:
 //         switch msg.Type {
 //         case KeyEnter:
 //             fmt.Println("you pressed enter!")
+//         case KeyRune:
+//             switch msg.Rune {
+//             case 'a':
+//                 fmt.Println("you pressed a!")
+//             }
 //         }
 //     }
 //
+//     // Switch on the string representation of the key (shorter)
 //     switch msg := msg.(type) {
 //     case KeyMsg:
 //         switch msg.String() {
 //         case "enter":
 //             fmt.Println("you pressed enter!")
+//         case "a':
+//             fmt.Println("you pressed a!")
 //         }
 //     }
 type KeyMsg Key

tea.go

@@ -1,7 +1,8 @@
-// Package tea provides an Elm-inspired framework for building rich terminal
-// user interfaces. It's well-suited for simple and complex terminal
-// applications, either inline, full-window, or a mix of both. It's been
-// battle-tested in several large projects and is production-ready.
+// Package tea provides a framework for building rich terminal user interfaces
+// based on the paradigms of The Elm Architecture. It's well-suited for simple
+// and complex terminal applications, either inline, full-window, or a mix of
+// both. It's been battle-tested in several large projects and is
+// production-ready.
 //
 // A tutorial is available at https://github.com/charmbracelet/bubbletea/tree/master/tutorials
 //