some name api changes, and more documentation

drivers/tcell/tcell.go

@@ -121,7 +121,7 @@ func (t *Driver) PollMsg() (gorltk.Msg, bool) {
 		case *tcell.EventInterrupt:
 			return nil, false
 		case *tcell.EventResize:
-			ev := gorltk.MsgWindowSize{}
+			ev := gorltk.MsgScreenSize{}
 			ev.Time = tev.When()
 			ev.Width, ev.Height = tev.Size()
 			return ev, true

drivers/tk/tk.go

@@ -192,7 +192,7 @@ func (tk *Driver) ClearCache() {
 	}
 }
 
-func (tk *Driver) getMsgKeyDown(s string) (gorltk.Msg, bool) {
+func getMsgKeyDown(s string) (gorltk.Msg, bool) {
 	var key gorltk.Key
 	switch s {
 	case "Down", "KP_2":
@@ -229,9 +229,9 @@ func (tk *Driver) getMsgKeyDown(s string) (gorltk.Msg, bool) {
 		if utf8.RuneCountInString(s) != 1 {
 			return "", false
 		}
-		key = Key(s)
+		key = gorltk.Key(s)
 	}
-	return gorltk.MsgKeyDown{Key: key, Time: time.Now()}
+	return gorltk.MsgKeyDown{Key: key, Time: time.Now()}, true
 }
 
 func (tk *Driver) PollMsg() (gorltk.Msg, bool) {

grid.go

@@ -43,18 +43,23 @@ type GridConfig struct {
 	Recording bool // whether to record frames to enable replay
 }
 
+// Frame contains the necessary information to draw the frame changes from a
+// frame to the next.
 type Frame struct {
 	Cells  []FrameCell // cells that changed from previous frame
 	Time   time.Time   // time of frame drawing: used for replay
 	Width  int         // width of the grid when the frame was produced
 	Height int         // height of the grid when the frame was produced
 }
 
+// FrameCell represents a drawing instructions of cell at a specific position
+// in the grid.
 type FrameCell struct {
 	Cell Cell
 	Pos  Position
 }
 
+// NewGrid returns a new grid.
 func NewGrid(cfg GridConfig) *Grid {
 	gd := &Grid{}
 	if cfg.Height <= 0 {
@@ -68,6 +73,7 @@ func NewGrid(cfg GridConfig) *Grid {
 	return gd
 }
 
+// Size returns the (width, height) of the grid in cells.
 func (gd *Grid) Size() (int, int) {
 	return gd.width, gd.height
 }
@@ -145,6 +151,11 @@ func (gd *Grid) Frames() []Frame {
 	return gd.frames
 }
 
+// ClearCache clears internal cache buffers, forcing a complete redraw of the
+// screen with next the Draw call, even for cells that did not change. This can
+// be used in the case the physical display and the internal model are not in
+// sync: for example after a resize, or after a change of the GetImage function
+// of the driver (on the fly change of the tileset).
 func (gd *Grid) ClearCache() {
 	for i := 0; i < len(gd.cellBackBuffer); i++ {
 		gd.cellBackBuffer[i] = Cell{}

messages.go

@@ -2,8 +2,10 @@ package gorltk
 
 import "time"
 
+// Key represents the name of a key press.
 type Key string
 
+// This is the list of the supported non single-character named keys.
 const (
 	KeyArrowDown  Key = "ArrowDown"
 	KeyArrowLeft  Key = "ArrowLeft"
@@ -35,8 +37,10 @@ func (ev MsgKeyDown) ShiftKey() bool {
 	return ev.shift
 }
 
+// MouseButton represents mouse buttons.
 type MouseButton int
 
+// This is the list of supported mouse buttons.
 const (
 	ButtonMain      MouseButton = iota // left button
 	ButtonAuxiliary                    // middle button
@@ -58,7 +62,8 @@ type MsgMouseMove struct {
 
 type msgQuit struct{}
 
-type MsgWindowSize struct {
+// MsgScreenSize is used to report the screen size.
+type MsgScreenSize struct {
 	Width  int       // width in cells
 	Height int       // height in cells
 	Time   time.Time // time when the event was generated

pos.go

@@ -2,6 +2,7 @@ package gorltk
 
 import "fmt"
 
+// Position represents an (X,Y) position in a grid.
 type Position struct {
 	X int
 	Y int

replay.go

@@ -2,9 +2,13 @@ package gorltk
 
 import "time"
 
-// Replay is an implementation of Model that replays a game from a list of
-// frames.
-type Replay struct {
+// NewReplay returns a Model that runs a replay of a game with the given
+// recorded frames.
+func NewReplay(frames []Frame) Model {
+	return &replay{Frames: frames}
+}
+
+type replay struct {
 	Frames []Frame
 	undo   [][]FrameCell
 	frame  int
@@ -16,87 +20,87 @@ type Replay struct {
 type repAction int
 
 const (
-	ReplayNone repAction = iota
-	ReplayNext
-	ReplayPrevious
-	ReplayTogglePause
-	ReplayQuit
-	ReplaySpeedMore
-	ReplaySpeedLess
+	replayNone repAction = iota
+	replayNext
+	replayPrevious
+	replayTogglePause
+	replayQuit
+	replaySpeedMore
+	replaySpeedLess
 )
 
 type msgTick int // frame number
 
-func (rep *Replay) Init() Cmd {
+func (rep *replay) Init() Cmd {
 	rep.auto = true
 	rep.speed = 1
 	rep.undo = [][]FrameCell{}
 	return rep.tick()
 }
 
-func (rep *Replay) Update(msg Msg) Cmd {
+func (rep *replay) Update(msg Msg) Cmd {
 	switch msg := msg.(type) {
 	case MsgKeyDown:
 		switch msg.Key {
 		case "Q", "q", KeyEscape:
-			rep.action = ReplayQuit
+			rep.action = replayQuit
 		case "p", "P", KeySpace:
-			rep.action = ReplayTogglePause
+			rep.action = replayTogglePause
 		case "+", ">":
-			rep.action = ReplaySpeedMore
+			rep.action = replaySpeedMore
 		case "-", "<":
-			rep.action = ReplaySpeedLess
+			rep.action = replaySpeedLess
 		case KeyArrowRight, KeyArrowDown, KeyEnter, "j", "n", "f":
-			rep.action = ReplayNext
+			rep.action = replayNext
 			rep.auto = false
 		case KeyArrowLeft, KeyArrowUp, KeyBackspace, "k", "N", "b":
-			rep.action = ReplayPrevious
+			rep.action = replayPrevious
 			rep.auto = false
 		}
 	case MsgMouseDown:
 		switch msg.Button {
 		case ButtonMain:
-			rep.action = ReplayTogglePause
+			rep.action = replayTogglePause
 		case ButtonAuxiliary:
-			rep.action = ReplayNext
-			rep.action = ReplayTogglePause
+			rep.action = replayNext
+			rep.action = replayTogglePause
 			rep.auto = false
 		case ButtonSecondary:
-			rep.action = ReplayPrevious
+			rep.action = replayPrevious
 			rep.auto = false
 		}
 	case msgTick:
 		if rep.auto && rep.frame == int(msg) {
-			rep.action = ReplayNext
+			rep.action = replayNext
 		}
 	}
 	switch rep.action {
-	case ReplayNext:
+	case replayNext:
 		if rep.frame >= len(rep.Frames) {
-			rep.action = ReplayNone
+			rep.action = replayNone
 			break
 		} else if rep.frame < 0 {
 			rep.frame = 0
 		}
 		rep.frame++
-	case ReplayPrevious:
+	case replayPrevious:
 		if rep.frame <= 1 {
-			rep.action = ReplayNone
+			rep.action = replayNone
 			break
 		} else if rep.frame >= len(rep.Frames) {
 			rep.frame = len(rep.Frames)
 		}
 		rep.frame--
-	case ReplayQuit:
+	case replayQuit:
 		return Quit
-	case ReplayTogglePause:
+	case replayTogglePause:
 		rep.auto = !rep.auto
-	case ReplaySpeedMore:
+	case replaySpeedMore:
 		rep.speed *= 2
 		if rep.speed > 16 {
 			rep.speed = 16
 		}
-	case ReplaySpeedLess:
+	case replaySpeedLess:
 		rep.speed /= 2
 		if rep.speed < 1 {
 			rep.speed = 1
@@ -105,9 +109,9 @@ func (rep *Replay) Update(msg Msg) Cmd {
 	return rep.tick()
 }
 
-func (rep *Replay) Draw(gd *Grid) {
+func (rep *replay) Draw(gd *Grid) {
 	switch rep.action {
-	case ReplayNext:
+	case replayNext:
 		df := rep.Frames[rep.frame-1]
 		rep.undo = append(rep.undo, []FrameCell{})
 		j := len(rep.undo) - 1
@@ -117,7 +121,7 @@ func (rep *Replay) Draw(gd *Grid) {
 			rep.undo[j] = append(rep.undo[j], FrameCell{Cell: c, Pos: dr.Pos})
 			gd.SetCell(dr.Pos, dr.Cell)
 		}
-	case ReplayPrevious:
+	case replayPrevious:
 		df := rep.undo[len(rep.undo)-1]
 		for _, dr := range df {
 			gd.SetCell(dr.Pos, dr.Cell)
@@ -126,7 +130,7 @@ func (rep *Replay) Draw(gd *Grid) {
 	}
 }
 
-func (rep *Replay) tick() Cmd {
+func (rep *replay) tick() Cmd {
 	if !rep.auto || rep.frame > len(rep.Frames)-1 || rep.frame < 0 {
 		return nil
 	}