First pass at documentations.

robot.go

@@ -8,6 +8,8 @@ import (
 	v "bitbucket.org/hackerbots/vector"
 )
 
+// Robot contains everything the game needs to know to simulate robot behavior.
+// Players have a []Robot
 type Robot struct {
 	Id             string      `json:"id"`
 	Name           string      `json:"name"`
@@ -35,6 +37,7 @@ type Robot struct {
 	idg            *IdGenerator
 }
 
+// Collision is basically a Point2d.
 type Collision struct {
 	v.Point2d
 	Type string `json:"type"`
@@ -50,6 +53,7 @@ type OtherRobot struct {
 	Health   int        `json:"health"`
 }
 
+// GetTruncatedDetails pares down our info into an OtherRobot.
 func (r Robot) GetTruncatedDetails() OtherRobot {
 	return OtherRobot{
 		Id:       r.Id,
@@ -60,6 +64,7 @@ func (r Robot) GetTruncatedDetails() OtherRobot {
 	}
 }
 
+// RobotSorter implements sort.Interface for OtherRobot
 type RobotSorter struct {
 	Robots []OtherRobot
 }
@@ -76,7 +81,7 @@ func (s RobotSorter) Less(i, j int) bool {
 	return s.Robots[i].Id < s.Robots[j].Id
 }
 
-// TODO - how do I not duplicate this code???
+// AllRobotSorter implements sort.Inteface for BotHealth
 type AllRobotSorter struct {
 	Robots []BotHealth
 }
@@ -93,6 +98,7 @@ func (s AllRobotSorter) Less(i, j int) bool {
 	return s.Robots[i].RobotId < s.Robots[j].RobotId
 }
 
+// Stats is the point allocation for a Robot.
 type Stats struct {
 	Hp            int     `json:"hp"`
 	Speed         float32 `json:"speed"`
@@ -105,8 +111,9 @@ type Stats struct {
 	WeaponSpeed   float32 `json:"weapon_speed"`
 }
 
-// We request stats using an integer between 1 and 100, the
-// integer values map to sensible min-max ranges
+// StatsRequest is the struct used in comunication with the player. We request
+// stats using an integer between 1 and 100, the integer values map to sensible
+// min-max ranges
 type StatsRequest struct {
 	Hp            int `json:"hp"`
 	Speed         int `json:"speed"`
@@ -119,6 +126,7 @@ type StatsRequest struct {
 	WeaponSpeed   int `json:"weapon_speed"`
 }
 
+// DeriveStats maps the 0-100 values to sensible in-game min-max values.
 func DeriveStats(request StatsRequest) Stats {
 	s := Stats{}
 
@@ -162,6 +170,7 @@ func DeriveStats(request StatsRequest) Stats {
 	return s
 }
 
+// Instruction is the struct a player sends each turn.
 type Instruction struct {
 	Message     *string     `json:"message,omitempty"`
 	MoveTo      *v.Point2d  `json:"move_to,omitempty"`
@@ -246,6 +255,7 @@ func (r *Robot) checkCollisions(g *Game, probe v.Vector2d) (bool, *v.Point2d, *R
 	return finalCollision, intersection, finalRobot
 }
 
+// Tick is the Robot's chance to udpate itself.
 func (r *Robot) Tick(g *Game) {
 	r.Collision = nil
 	r.Hit = false
@@ -397,6 +407,7 @@ func (r *Robot) Tick(g *Game) {
 	}
 }
 
+// scan updates the robots field of view if it's in teh appropriate mode
 func (r *Robot) scan(g *Game) {
 	r.Scanners = r.Scanners[:0]
 	for player := range g.players {
@@ -443,6 +454,7 @@ func (r *Robot) scan(g *Game) {
 
 }
 
+// fire is called according to player instruction. XXX: There is a race here...
 func (r *Robot) fire(g *Game) *Projectile {
 	// Throttle the fire rate
 	time_since_fired := (float32(g.turn) * (r.Delta * 1000)) - (float32(r.LastFired) * (r.Delta * 1000))
@@ -465,6 +477,7 @@ func (r *Robot) fire(g *Game) *Projectile {
 	}
 }
 
+// reset is called to move a robot to a reasonable location at game start time.
 func (r *Robot) reset(g *Game) {
 	for {
 		start_pos := v.Point2d{