First pass at documentations.

protocol.go

@@ -7,16 +7,15 @@ import (
 	"code.google.com/p/go.net/websocket"
 )
 
-// < the name of the game we want to join
+// GameID is essentially the name of the game we want to join
 type GameID struct {
 	Id string `json:"id"`
 }
 
-// > identify
+// PlayerID is the internal hash we give to a client
 type PlayerID struct {
 	Type string `json:"type"`
 	Hash string `json:"id"`
-	Failure
 }
 
 func NewPlayerID(id string) *PlayerID {
@@ -26,13 +25,15 @@ func NewPlayerID(id string) *PlayerID {
 	}
 }
 
-// < [robot | spectator], name, client-type, game ID
+// ClientID is how a player wants to be known
 type ClientID struct {
 	Type      string `json:"type"`
 	Name      string `json:"name"`
 	Useragent string `json:"useragent"`
 }
 
+// ClientID.Valid is used to be sure the player connecting is of appropriate
+// type.
 func (c *ClientID) Valid() (bool, string) {
 	switch c.Type {
 	case "robot", "spectator":
@@ -41,11 +42,14 @@ func (c *ClientID) Valid() (bool, string) {
 	return false, "useragent must be 'robot' or 'spectator'"
 }
 
+// ClientConfig embodies a map of stats requests
 type ClientConfig struct {
 	ID    string                  `json:"id"`
 	Stats map[string]StatsRequest `json:"stats"`
 }
 
+// ClientConfig.Valid is what determins if a player has asked for too many
+// points.
 func (config ClientConfig) Valid(max int) bool {
 	total := 0
 	for _, s := range config.Stats {
@@ -65,11 +69,15 @@ func (config ClientConfig) Valid(max int) bool {
 	return true
 }
 
+// BoardSize is the response containing the geometry of the requested game.
 type BoardSize struct {
 	Width  float32 `json:"width"`
 	Height float32 `json:"height"`
 }
 
+// GameParam is sent to the client to tell them of the geometry of the game
+// requested, how many points they may use, and what encoding the server will
+// use to communicate with the client.
 type GameParam struct {
 	// TODO: should have information about max points in here
 	BoardSize BoardSize `json:"boardsize"`
@@ -78,8 +86,8 @@ type GameParam struct {
 	Type      string    `json:"type"`
 }
 
-// > [OK | FULL | NOT AUTH], board size, game params
-
+// Handshake is simply the response to a client to let them know if the number
+// of stats they've asked for is reasonable. If false it means try again.
 type Handshake struct {
 	ID      string `json:"id"`
 	Success bool   `json:"success"`
@@ -94,9 +102,14 @@ func NewHandshake(id string, success bool) *Handshake {
 	}
 }
 
-type Message interface {
-}
+// Message is an empty interface used to send out arbitrary JSON/gob to
+// clients, both players/spectators. We might send out Boardstate or GameOver,
+// hence the interface{}.
+type Message interface{}
 
+// Boardstate is the main struct calculated every tick (per player) and sent
+// out to clients. It contains the appropriate subset of all data needed by
+// each player/spectator.
 type Boardstate struct {
 	MyRobots    []Robot      `json:"my_robots"`
 	OtherRobots []OtherRobot `json:"robots"`
@@ -120,6 +133,7 @@ func NewBoardstate() *Boardstate {
 	}
 }
 
+// Special outbound message with a []string of winners.
 type GameOver struct {
 	Winners []string `json:"winners"`
 	Type    string   `json:"type"`
@@ -132,6 +146,8 @@ func NewGameOver() *GameOver {
 	}
 }
 
+// Failure is a simple stuct that is typically converted to JSON and  sent out
+// to the clients so they can know why something has failed.
 type Failure struct {
 	Reason string `json:"reason"`
 	Type   string `json:"type"`
@@ -144,6 +160,8 @@ func NewFailure(reason string) *Failure {
 	}
 }
 
+// Controller.AddPlayer is the HTTP -> websocket route that is used to
+// negociate a connection with a player/spectator.
 func (c *Controller) AddPlayer(ws *websocket.Conn) {
 	var gid GameID
 	err := websocket.JSON.Receive(ws, &gid)
@@ -324,9 +342,9 @@ encodingLoops:
 			game.unregister <- p
 			log.Printf("%s, %s: unregistered player", gid.Id, p.Id)
 		}()
-		go p.sender()
+		go p.Sender()
 		log.Printf("%s -> %s: p.sender went", gid.Id, p.Id)
-		p.recv()
+		p.Recv()
 		log.Printf(
 			"%s (player):  %v (robot) has been disconnected from %s (game)",
 			p.Id,
@@ -343,9 +361,9 @@ encodingLoops:
 			game.sunregister <- s
 			log.Printf("%s, %s: unregistered spectator", gid.Id, s.Id)
 		}()
-		go s.sender()
+		go s.Sender()
 		log.Printf("%s -> %s: s.sender went", gid.Id, s.Id)
-		s.recv()
+		s.Recv()
 		log.Printf("game %s: spectator %+v has been disconnected from this game", gid.Id, s)
 	}
 	log.Printf("exiting AddPlayer")