From c0f67a2927cf1bb42f57564083dfd8a457a5e71e Mon Sep 17 00:00:00 2001 From: Christian Rocha Date: Wed, 29 Jul 2020 20:49:20 -0400 Subject: [PATCH] Improve GoDocs --- key.go | 45 ++++++++++++++++++++++++++++++++++++++++----- logging.go | 2 +- renderer.go | 17 +++++++++-------- tea.go | 19 ++++++++++++++----- 4 files changed, 64 insertions(+), 19 deletions(-) diff --git a/key.go b/key.go index cd514e5..c83f1a8 100644 --- a/key.go +++ b/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 diff --git a/logging.go b/logging.go index 6455c05..cde1470 100644 --- a/logging.go +++ b/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. // diff --git a/renderer.go b/renderer.go index 9143aac..b6ae0d5 100644 --- a/renderer.go +++ b/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 { diff --git a/tea.go b/tea.go index 6bb6318..9ff8ee3 100644 --- a/tea.go +++ b/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() {