First pass at documentations.

control.go

@@ -13,13 +13,18 @@ import (
 	"sync"
 )
 
+// JsonHandler is a function type that allows setting the Content-Type
+// appropriately for views destined to serve JSON
 type JsonHandler func(http.ResponseWriter, *http.Request)
 
+// ServeHTTP is JsonHandler's http.Handler implementation.
 func (h JsonHandler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	h(w, req)
 }
 
+// Controller is the shepherd of a collection of games. The main package in
+// botserv simply populates one of these and starts an http server.
 type Controller struct {
 	Idg        *IdGenerator
 	Conf       Config
@@ -28,6 +33,9 @@ type Controller struct {
 	Profile    string
 }
 
+// NewController takes a populated Config, and some parameters to determine
+// what sorts of profiling to deal with and returns a freshly populated
+// Controller.
 func NewController(conf Config, mprof, pprof string) *Controller {
 	idg := NewIdGenerator()
 	return &Controller{
@@ -41,11 +49,15 @@ func NewController(conf Config, mprof, pprof string) *Controller {
 	}
 }
 
-// TODO Eventually this thing will have a select loop for dealing with game access in a more lock-free manner?
+// TODO Eventually this thing will have a select loop for dealing with game
+// access in a more lock-free manner?
 func (c *Controller) Run() {
 	c.Idg.Run()
 }
 
+// StartGame is the http route responsible for responding to requests to start
+// games under this controller. Creates a default Config object, and populates
+// it according to data POSTed.
 func (c *Controller) StartGame(w http.ResponseWriter, req *http.Request) {
 	log.Println("asked to create a game")
 
@@ -112,6 +124,8 @@ func (c *Controller) StartGame(w http.ResponseWriter, req *http.Request) {
 	}
 }
 
+// ListGames makes a reasonable JSON response based on the games currently
+// being run.
 func (c *Controller) ListGames(w http.ResponseWriter, req *http.Request) {
 	log.Println("games list requested")
 	c.Games.RLock()
@@ -146,6 +160,8 @@ func (c *Controller) ListGames(w http.ResponseWriter, req *http.Request) {
 	}
 }
 
+// GameStats provides an control mechanism to query for the stats of a single
+// game
 func (c *Controller) GameStats(w http.ResponseWriter, req *http.Request) {
 	// TODO: wrap this up in something similar to the JsonHandler to verify the
 	// url? Look at gorilla routing?
@@ -171,6 +187,8 @@ func (c *Controller) GameStats(w http.ResponseWriter, req *http.Request) {
 	}
 }
 
+// BW provides a route to query for current bandwidth utilization for a single
+// game.
 func (c *Controller) BW(w http.ResponseWriter, req *http.Request) {
 	// TODO: wrap this up in something similar to the JsonHandler to verify the
 	// url? Look at gorilla routing?
@@ -198,7 +216,8 @@ func (c *Controller) BW(w http.ResponseWriter, req *http.Request) {
 	}
 }
 
-// StopGame is the only mechanism to decrease the number of running games in a Controller
+// StopGame is the only mechanism to decrease the number of running games in
+// a Controller
 func (c *Controller) StopGame(w http.ResponseWriter, req *http.Request) {
 	key, err := c.getGameId(req.URL.Path)
 	if err != nil {
@@ -228,6 +247,8 @@ func (c *Controller) StopGame(w http.ResponseWriter, req *http.Request) {
 	log.Printf("returning from StopGame")
 }
 
+// KillServer is my favorite method of all the methods in botserv: it shuts
+// things down respecting profiling requests.
 func (c *Controller) KillServer(w http.ResponseWriter, req *http.Request) {
 	if c.Profile != "" {
 		log.Print("trying to stop cpu profile")
@@ -247,6 +268,9 @@ func (c *Controller) KillServer(w http.ResponseWriter, req *http.Request) {
 	log.Fatal("shit got fucked up")
 }
 
+// Index is the function for handling all traffic not officially in the API. It
+// just lets people know that this is a hackerbots server running at
+// a particular version.
 func (c *Controller) Index(w http.ResponseWriter, req *http.Request) {
 	log.Println("version requested")
 	version := struct {
@@ -261,6 +285,8 @@ func (c *Controller) Index(w http.ResponseWriter, req *http.Request) {
 	}
 }
 
+// getGameId trims the gameid off of the url. This is hokey, and makes me miss
+// django regex-specified routes.
 func (c *Controller) getGameId(path string) (string, error) {
 	var err error
 	trimmed := strings.Trim(path, "/")
@@ -273,6 +299,7 @@ func (c *Controller) getGameId(path string) (string, error) {
 }
 
 // MapLock is simply a map and a RWMutex
+// TODO: obviate the need for this in Controller.Run
 type MapLock struct {
 	M map[string]*Game
 	sync.RWMutex