Improve GoDocs

key.go

@@ -7,10 +7,32 @@ import (
 	"unicode/utf8"
 )
 
-// KeyMsg contains information about a keypress.
+// KeyMsg contains information about a keypress. KeyMsgs are always sent to
+// the program's update function. There are a couple general patterns you could
+// use to check for keypresses:
+//
+//     switch msg := msg.(type) {
+//     case KeyMsg:
+//         switch msg.Type {
+//             case KeyEnter:
+//                 fmt.Println("you pressed enter!")
+//         }
+//     }
+//
+//     switch msg := msg.(type) {
+//     case KeyMsg:
+//         switch msg.String() {
+//             case "enter":
+//                 fmt.Println("you pressed enter!")
+//         }
+//     }
 type KeyMsg Key
 
 // String returns a friendly name for a key.
+//
+//     k := KeyType{Type: KeyEnter}
+//     fmt.Println(k)
+//     // Output: enter
 func (k *KeyMsg) String() (str string) {
 	if k.Alt {
 		str += "alt+"
@@ -25,7 +47,7 @@ func (k *KeyMsg) String() (str string) {
 	return ""
 }
 
-// IsRune returns weather or not the key is a rune.
+// IsRune returns whether or not the key is a rune.
 func (k *KeyMsg) IsRune() bool {
 	return k.Type == KeyRune
 }
@@ -37,7 +59,20 @@ type Key struct {
 	Alt  bool
 }
 
-// KeyType indicates the key pressed.
+// KeyType indicates the key pressed, such as KeyEnter or KeyBreak or
+// KeyCtrlC. All other keys will be type KeyRune. To get the rune value, check
+// the Rune method on a Key struct, or use the Key.String() method:
+//
+//     k := Key{Type: KeyRune, Rune: 'a', Alt: true}
+//     if k.Type == KeyRune {
+//
+//         fmt.Println(k.Rune)
+//         // Output: a
+//
+//         fmt.Println(k.String())
+//         // Output: alt+a
+//
+//     }
 type KeyType int
 
 // Control keys. I know we could do this with an iota, but the values are very
@@ -82,7 +117,7 @@ const (
 	keyDEL = 127 // delete. on most systems this is mapped to backspace, I hear
 )
 
-// Aliases
+// Control key aliases:
 const (
 	KeyNull      = keyNUL
 	KeyBreak     = keyETX
@@ -129,7 +164,7 @@ const (
 	KeyCtrlQuestionMark = keyDEL // ctrl+?
 )
 
-// Other keys we track
+// Other keys:
 const (
 	KeyRune = -(iota + 1)
 	KeyUp

logging.go

@@ -5,7 +5,7 @@ import (
 	"os"
 )
 
-// LogToFile sets up default logging to log to a file This is helpful as we
+// LogToFile sets up default logging to log to a file. This is helpful as we
 // can't print to the terminal since our TUI is occupying it. If the file
 // doesn't exist it will be created.
 //

renderer.go

@@ -326,9 +326,9 @@ type syncScrollAreaMsg struct {
 	bottomBoundary int
 }
 
-// SyncScrollArea performs a paint of the entire scroll area. This is required
-// to initialize the scrollable region and should also be called on resize
-// (WindowSizeMsg).
+// SyncScrollArea performs a paint of the entire region designated to be the
+// scrollable area. This is required to initialize the scrollable region and
+// should also be called on resize (WindowSizeMsg).
 //
 // For high-performance, scroll-based rendering only.
 func SyncScrollArea(lines []string, topBoundary int, bottomBoundary int) Cmd {
@@ -357,8 +357,9 @@ type scrollUpMsg struct {
 	bottomBoundary int
 }
 
-// ScrollUp adds lines to the top of the scrollable region, pushing lines below
-// down. Lines that are pushed out the scrollable region disappear from view.
+// ScrollUp adds lines to the top of the scrollable region, pushing existing
+// lines below down. Lines that are pushed out the scrollable region disappear
+// from view.
 //
 // For high-performance, scroll-based rendering only.
 func ScrollUp(newLines []string, topBoundary, bottomBoundary int) Cmd {
@@ -377,9 +378,9 @@ type scrollDownMsg struct {
 	bottomBoundary int
 }
 
-// ScrollDown adds lines to the bottom of the scrollable region, pushing lines
-// above up. Lines that are pushed out of the scrollable region disappear from
-// view.
+// ScrollDown adds lines to the bottom of the scrollable region, pushing
+// existing lines above up. Lines that are pushed out of the scrollable region
+// disappear from view.
 //
 // For high-performance, scroll-based rendering only.
 func ScrollDown(newLines []string, topBoundary, bottomBoundary int) Cmd {

tea.go

@@ -1,3 +1,11 @@
+// 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.
+//
+// A tutorial is available at https://github.com/charmbracelet/bubbletea/tree/master/tutorials
+//
+// Example programs can be found at https://github.com/charmbracelet/bubbletea/tree/master/examples
 package tea
 
 import (
@@ -59,7 +67,7 @@ type Program struct {
 	altScreenActive bool
 }
 
-// Quit is a special command that tells the program to exit.
+// Quit is a special command that tells the Bubble Tea program to exit.
 func Quit() Msg {
 	return quitMsg{}
 }
@@ -194,7 +202,8 @@ func (p *Program) Start() error {
 	}
 }
 
-// EnterAltScreen enters the alternate screen buffer.
+// EnterAltScreen enters the alternate screen buffer, which consumes the entire
+// terminal window. ExitAltScreen will return the terminal to its former state.
 func (p *Program) EnterAltScreen() {
 	p.mtx.Lock()
 	defer p.mtx.Unlock()
@@ -219,15 +228,15 @@ func (p *Program) ExitAltScreen() {
 	}
 }
 
-// EnableMouseCellMotion enables mouse click, release, wheel and motion events if a
-// button is pressed.
+// EnableMouseCellMotion enables mouse click, release, wheel and motion events
+// if a button is pressed.
 func (p *Program) EnableMouseCellMotion() {
 	p.mtx.Lock()
 	defer p.mtx.Unlock()
 	fmt.Fprintf(p.output, te.CSI+te.EnableMouseCellMotionSeq)
 }
 
-// DisableMouseCellMotino disables Mouse Cell Motion tracking. If you've
+// DisableMouseCellMotion disables Mouse Cell Motion tracking. If you've
 // enabled Cell Motion mouse trakcing be sure to call this as your program is
 // exiting or your users will be very upset!
 func (p *Program) DisableMouseCellMotion() {