Code cleanup and comments

8 files changed, 36 insertions, 65 deletions

diff --git a/termui/block.go b/termui/block.go
index 6d8602a..cc3a15c 100644
--- a/termui/block.go
+++ b/termui/block.go
@@ -4,15 +4,13 @@ import (
 	"image"
 )
 
-// Block is a base struct for all other upper level widgets,
-// consider it as css: display:block.
-// Normally you do not need to create it manually.
+// Block is a base struct for all other upper level widgets.
 type Block struct {
 	Grid     image.Rectangle
-	X        int
-	Y        int
-	XOffset  int
-	YOffset  int
+	X        int // largest X value in the inner square
+	Y        int // largest Y value in the inner square
+	XOffset  int // the X position of the widget on the terminal
+	YOffset  int // the Y position of the widget on the terminal
 	Label    string
 	BorderFg Color
 	BorderBg Color
@@ -22,7 +20,7 @@ type Block struct {
 	Bg       Color
 }
 
-// NewBlock returns a *Block which inherits styles from current theme.
+// NewBlock returns a *Block which inherits styles from the current theme.
 func NewBlock() *Block {
 	return &Block{
 		Fg:       Theme.Fg,
@@ -34,7 +32,6 @@ func NewBlock() *Block {
 	}
 }
 
-// Buffer draws a box border.
 func (b *Block) drawBorder(buf *Buffer) {
 	x := b.X + 1
 	y := b.Y + 1
@@ -67,7 +64,7 @@ func (b *Block) drawLabel(buf *Buffer) {
 	}
 }
 
-// Resize computes Height, Width, XOffset, and YOffset
+// Resize computes Height, Width, XOffset, and YOffset given terminal dimensions.
 func (b *Block) Resize(termWidth, termHeight, termCols, termRows int) {
 	b.X = int((float64(b.Grid.Dx())/float64(termCols))*float64(termWidth)) - 2
 	b.Y = int((float64(b.Grid.Dy())/float64(termRows))*float64(termHeight)) - 2
@@ -75,6 +72,7 @@ func (b *Block) Resize(termWidth, termHeight, termCols, termRows int) {
 	b.YOffset = int(((float64(b.Grid.Min.Y) / float64(termRows)) * float64(termHeight)))
 }
 
+// SetGrid create a rectangle representing the block's dimensions in the grid.
 func (b *Block) SetGrid(c0, r0, c1, r1 int) {
 	b.Grid = image.Rect(c0, r0, c1, r1)
 }
@@ -87,7 +85,7 @@ func (b *Block) GetYOffset() int {
 	return b.YOffset
 }
 
-// Buffer implements Bufferer interface and draws background and border
+// Buffer implements Bufferer interface and draws background, border, and borderlabel.
 func (b *Block) Buffer() *Buffer {
 	buf := NewBuffer()
 	buf.SetAreaXY(b.X+2, b.Y+2)
diff --git a/termui/buffer.go b/termui/buffer.go
index 3881b03..bab7e30 100644
--- a/termui/buffer.go
+++ b/termui/buffer.go
@@ -4,7 +4,7 @@ import (
 	"image"
 )
 
-// Cell is a rune with assigned Fg and Bg
+// Cell is a rune with assigned Fg and Bg.
 type Cell struct {
 	Ch rune
 	Fg Color
@@ -21,14 +21,13 @@ func NewCell(ch rune, Fg, Bg Color) Cell {
 	return Cell{ch, Fg, Bg}
 }
 
-// NewBuffer returns a new Buffer
 func NewBuffer() *Buffer {
 	return &Buffer{
 		CellMap: make(map[image.Point]Cell),
 		Area:    image.Rectangle{}}
 }
 
-// NewFilledBuffer returns a new Buffer filled with ch, fb and bg.
+// NewFilledBuffer returns a new Buffer filled with the given Cell.
 func NewFilledBuffer(x0, y0, x1, y1 int, c Cell) *Buffer {
 	buf := NewBuffer()
 	buf.Area.Min = image.Pt(x0, y0)
@@ -42,11 +41,12 @@ func NewFilledBuffer(x0, y0, x1, y1 int, c Cell) *Buffer {
 	return buf
 }
 
-// Set assigns a char to (x,y)
+// Set assigns a Cell to (x,y).
 func (b *Buffer) SetCell(x, y int, c Cell) {
 	b.CellMap[image.Pt(x, y)] = c
 }
 
+// SetString assigns a string to a Buffer starting at (x,y).
 func (b *Buffer) SetString(x, y int, s string, fg, bg Color) {
 	for i, char := range s {
 		b.SetCell(x+i, y, Cell{char, fg, bg})
@@ -58,32 +58,13 @@ func (b *Buffer) At(x, y int) Cell {
 	return b.CellMap[image.Pt(x, y)]
 }
 
-// Bounds returns the domain for which At can return non-zero color.
-func (b *Buffer) Bounds() image.Rectangle {
-	x0, y0, x1, y1 := 0, 0, 0, 0
-	for p := range b.CellMap {
-		if p.X > x1 {
-			x1 = p.X
-		}
-		if p.X < x0 {
-			x0 = p.X
-		}
-		if p.Y > y1 {
-			y1 = p.Y
-		}
-		if p.Y < y0 {
-			y0 = p.Y
-		}
-	}
-	return image.Rect(x0, y0, x1+1, y1+1)
-}
-
 // SetArea assigns a new rect area to Buffer b.
 func (b *Buffer) SetArea(r image.Rectangle) {
 	b.Area.Max = r.Max
 	b.Area.Min = r.Min
 }
 
+// SetAreaXY sets the Buffer bounds from (0,0) to (x,y).
 func (b *Buffer) SetAreaXY(x, y int) {
 	b.Area.Min.Y = 0
 	b.Area.Min.X = 0
@@ -91,12 +72,7 @@ func (b *Buffer) SetAreaXY(x, y int) {
 	b.Area.Max.X = x
 }
 
-// Sync sets drawing area to the buffer's bound
-func (b *Buffer) Sync() {
-	b.SetArea(b.Bounds())
-}
-
-// Merge merges bs Buffers onto b
+// Merge merges the given buffers onto the current Buffer.
 func (b *Buffer) Merge(bs ...*Buffer) {
 	for _, buf := range bs {
 		for p, c := range buf.CellMap {
@@ -106,6 +82,7 @@ func (b *Buffer) Merge(bs ...*Buffer) {
 	}
 }
 
+// MergeWithOffset merges the given buffer at a certain position on the given buffer.
 func (b *Buffer) MergeWithOffset(buf *Buffer, xOffset, yOffset int) {
 	for p, c := range buf.CellMap {
 		b.SetCell(p.X+xOffset, p.Y+yOffset, c)
@@ -114,7 +91,7 @@ func (b *Buffer) MergeWithOffset(buf *Buffer, xOffset, yOffset int) {
 	b.SetArea(b.Area.Union(rect))
 }
 
-// Fill fills the Buffer b with ch,fg and bg.
+// Fill fills the Buffer with a Cell.
 func (b *Buffer) Fill(c Cell) {
 	for x := b.Area.Min.X; x < b.Area.Max.X; x++ {
 		for y := b.Area.Min.Y; y < b.Area.Max.Y; y++ {
diff --git a/termui/colors.go b/termui/colors.go
index 469fd15..d8dc8bf 100644
--- a/termui/colors.go
+++ b/termui/colors.go
@@ -1,15 +1,19 @@
 package termui
 
+// Color is an integer in the range -1 to 255
 type Color int
 
+// ColorDefault = clear
 const ColorDefault = -1
 
+// Copied from termbox
 const (
 	AttrBold Color = 1 << (iota + 9)
 	AttrUnderline
 	AttrReverse
 )
 
+// Theme is assigned to the current theme
 var Theme = DefaultTheme
 
 var DefaultTheme = Colorscheme{
@@ -29,7 +33,7 @@ var DefaultTheme = Colorscheme{
 	TempHigh:    1,
 }
 
-// A ColorScheme represents the current look-and-feel of the dashboard.
+// A Colorscheme represents the current look-and-feel of the dashboard.
 type Colorscheme struct {
 	Fg Color
 	Bg Color
diff --git a/termui/events.go b/termui/events.go
index 836740b..30c6581 100644
--- a/termui/events.go
+++ b/termui/events.go
@@ -15,11 +15,12 @@ var eventStream = EventStream{
 
 type EventStream struct {
 	eventHandlers map[string]func(Event)
-	prevKey       string
+	prevKey       string // previous keypress
 	stopLoop      chan bool
-	eventQueue    chan tb.Event
+	eventQueue    chan tb.Event // list of events from termbox
 }
 
+// Event includes only the termbox.Event attributes we need.
 type Event struct {
 	Key    string
 	Width  int
@@ -137,7 +138,6 @@ func convertTermboxKeyValue(e tb.Event) string {
 	return pre + mod + k
 }
 
-// convertTermboxMouseValue turns termbox mouse events into strings
 func convertTermboxMouseValue(e tb.Event) string {
 	switch e.Key {
 	case tb.MouseLeft:
diff --git a/termui/grid.go b/termui/grid.go
index b0eb7e4..c8321a2 100644
--- a/termui/grid.go
+++ b/termui/grid.go
@@ -9,19 +9,21 @@ type GridBufferer interface {
 	SetGrid(int, int, int, int)
 }
 
+// Grid holds widgets and information about terminal dimensions.
+// Widgets are adjusted and rendered through the grid.
 type Grid struct {
 	Widgets []GridBufferer
 	Width   int
 	Height  int
 	Cols    int
 	Rows    int
-	BgColor Color
 }
 
 func NewGrid() *Grid {
 	return &Grid{}
 }
 
+// Set takes a widget along with it's grid dimensions to be controlled by the grid.
 func (g *Grid) Set(x0, y0, x1, y1 int, widget GridBufferer) {
 	if widget == nil {
 		return
@@ -36,13 +38,14 @@ func (g *Grid) Set(x0, y0, x1, y1 int, widget GridBufferer) {
 	g.Widgets = append(g.Widgets, widget)
 }
 
+// Resize resizes each widget in the grid's control.
 func (g *Grid) Resize() {
 	for _, w := range g.Widgets {
 		w.Resize(g.Width, g.Height, g.Cols, g.Rows)
 	}
 }
 
-// Buffer implements Bufferer interface.
+// Buffer implements Bufferer interface and merges each widget into one buffer.
 func (g *Grid) Buffer() *Buffer {
 	buf := NewFilledBuffer(0, 0, g.Width, g.Height, Cell{' ', ColorDefault, Theme.Bg})
 	for _, w := range g.Widgets {
diff --git a/termui/init.go b/termui/init.go
index a48ecfc..764de2b 100644
--- a/termui/init.go
+++ b/termui/init.go
@@ -14,17 +14,13 @@ func Init() error {
 	tb.SetOutputMode(tb.Output256)
 
 	Body = NewGrid()
-	Body.BgColor = Theme.Bg
-
-	// renderLock.Lock()
 	Body.Width, Body.Height = tb.Size()
-	// renderLock.Unlock()
 
 	return nil
 }
 
-// Close finalizes termui library,
-// should be called after successful initialization when termui's functionality isn't required anymore.
+// Close finalizes termui library.
+// It should be called after successful initialization when termui's functionality isn't required anymore.
 func Close() {
 	tb.Close()
 }
diff --git a/termui/render.go b/termui/render.go
index 92a277a..52bcdf3 100644
--- a/termui/render.go
+++ b/termui/render.go
@@ -6,19 +6,14 @@ import (
 	tb "github.com/nsf/termbox-go"
 )
 
-var renderJobs chan []Bufferer
-
-// So that only one render function can flush/write to the screen at a time
-// var renderLock sync.Mutex
-
-// Bufferer should be implemented by all renderable components. Bufferers can render a Buffer.
+// Bufferer should be implemented by all renderable components.
 type Bufferer interface {
 	Buffer() *Buffer
 	GetXOffset() int
 	GetYOffset() int
 }
 
-// Render renders all Bufferer in the given order from left to right, right could overlap on left ones.
+// Render renders all Bufferers in the given order to termbox, then asks termbox to print the screen.
 func Render(bs ...Bufferer) {
 	var wg sync.WaitGroup
 	for _, b := range bs {
@@ -35,13 +30,11 @@ func Render(bs ...Bufferer) {
 		}(b)
 	}
 
-	// renderLock.Lock()
-
 	wg.Wait()
 	tb.Flush()
-	// renderLock.Unlock()
 }
 
+// Clear clears the screen with the default Bg color.
 func Clear() {
 	tb.Clear(tb.ColorDefault+1, tb.Attribute(Theme.Bg)+1)
 }
diff --git a/termui/utils.go b/termui/utils.go
index 4f4ef63..c8f4da3 100644
--- a/termui/utils.go
+++ b/termui/utils.go
@@ -6,7 +6,7 @@ import (
 
 const DOTS = '…'
 
-// MaxString trims a string and adds dots if its length is greater than l
+// MaxString trims a string and adds dots if the string is longer than a give length.
 func MaxString(s string, l int) string {
 	if l <= 0 {
 		return ""