From 6fcdf9908f58014578da667fdb9258745ee203ad Mon Sep 17 00:00:00 2001
From: Christian Rocha <christian@rocha.is>
Date: Thu, 30 Jul 2020 11:29:20 -0400
Subject: [PATCH] Improve examples in docs

---
 commands.go | 24 +++++++++++++++++++++---
 key.go      | 17 +++++++++++++----
 tea.go      |  9 +++++----
 3 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/commands.go b/commands.go
index 0a11733..5220d64 100644
--- a/commands.go
+++ b/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)
diff --git a/key.go b/key.go
index 54c84fd..4424075 100644
--- a/key.go
+++ b/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 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 "enter":
+//             fmt.Println("you pressed enter!")
+//         case "a':
+//             fmt.Println("you pressed a!")
 //         }
 //     }
 type KeyMsg Key
diff --git a/tea.go b/tea.go
index fa62b91..83c4687 100644
--- a/tea.go
+++ b/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
 //