Godoc fixes (#898)

Add some godoc comments for the api/agent package and some of its
subpackages.

api/agent/agent.go

@@ -43,17 +43,17 @@ import (
 // TODO it would be really nice if we made the ramToken wrap the driver cookie (less brittle,
 // if those leak the container leaks too...) -- not the allocation, but the token.Close and cookie.Close
 // TODO if machine is out of ram, just timeout immediately / wait for hot slot? (discuss policy)
-//
+
 // Agent exposes an api to create calls from various parameters and then submit
 // those calls, it also exposes a 'safe' shutdown mechanism via its Close method.
 // Agent has a few roles:
-// * manage the memory pool for a given server
-// * manage the container lifecycle for calls (hot+cold)
-// * execute calls against containers
-// * invoke Start and End for each call appropriately
-// * check the mq for any async calls, and submit them
+//	* manage the memory pool for a given server
+//	* manage the container lifecycle for calls (hot+cold)
+//	* execute calls against containers
+//	* invoke Start and End for each call appropriately
+//	* check the mq for any async calls, and submit them
 //
-// overview:
+// Overview:
 // Upon submission of a call, Agent will start the call's timeout timer
 // immediately. If the call is hot, Agent will attempt to find an active hot
 // container for that route, and if necessary launch another container. Cold
@@ -69,7 +69,6 @@ import (
 // sending any input, if hot. call.End will be called regardless of the
 // timeout timer's status if the call was executed, and that error returned may
 // be returned from Submit.
-
 type Agent interface {
 	// GetCall will return a Call that is executable by the Agent, which
 	// can be built via various CallOpt's provided to the method.
@@ -117,6 +116,7 @@ type agent struct {
 	shutdown chan struct{}
 }
 
+// New creates an Agent that executes functions locally as Docker containers.
 func New(da DataAccess) Agent {
 	a := createAgent(da, true).(*agent)
 	a.wg.Add(1)

api/agent/doc.go

@@ -0,0 +1,26 @@
+// Package agent defines the Agent interface and related concepts. An agent is
+// an entity that knows how to execute an Fn function.
+//
+// The Agent Interface
+//
+// The Agent interface is the heart of this package. Agent exposes an api to
+// create calls from various parameters and then execute those calls. An Agent
+// has a few roles:
+//	* manage the memory pool for a given server
+//	* manage the container lifecycle for calls (hot+cold)
+//	* execute calls against containers
+//	* invoke Start and End for each call appropriately
+//	* check the mq for any async calls, and submit them
+//
+// For more information about how an agent executes a call see the
+// documentation on the Agent interface.
+//
+// Variants
+//
+// There are two flavors of runner, the local Docker agent and a load-balancing
+// agent. To create an agent that uses Docker containers to execute calls, use
+// New().
+//
+// To create an agent that can load-balance across a pool of sub-agents, use
+// NewLBAgent().
+package agent

api/agent/drivers/doc.go

@@ -0,0 +1,14 @@
+// Package drivers is intended as a general purpose container abstraction
+// library. It abstracts across the differences between different container
+// runtimes (e.g. Docker, Rkt, etc.) and provides utlities and data types that
+// are common across all runtimes.
+//
+// Docker Driver
+//
+// The docker driver runs functions as Docker containers.
+//
+// Mock Driver
+//
+// The mock driver pretends to run functions but doesn't actually run them. This
+// is for testing only.
+package drivers

api/agent/drivers/docker/doc.go

@@ -0,0 +1,5 @@
+// Package docker provides a Docker driver for Fn. Provides an implementation
+// of
+//	github.com/fnproject/fn/api/agent/drivers.Driver
+// that knows how to run Docker images.
+package docker

api/agent/drivers/mock/mocker.go

@@ -1,3 +1,4 @@
+// Package mock provides a fake Driver implementation that is only used for testing.
 package mock
 
 import (

api/agent/lb_agent.go

@@ -102,6 +102,8 @@ type lbAgent struct {
 	shutdown chan struct{}
 }
 
+// NewLBAgent creates an Agent that knows how to load-balance function calls
+// across a group of runner nodes.
 func NewLBAgent(da DataAccess, rp pool.RunnerPool, p pool.Placer) (Agent, error) {
 	agent := createAgent(da, false)
 	a := &lbAgent{

api/agent/protocol/doc.go

@@ -0,0 +1,12 @@
+// Package protocol defines the protocol between the Fn Agent and the code
+// running inside of a container. When an Fn Agent wants to perform a function
+// call it needs to pass that call to a container over stdin. The call is
+// encoded in one of the following protocols.
+//
+//	* Default I/O Format
+//	* JSON I/O Format
+//	* HTTP I/O Format
+//
+// For more information on the function formats see
+// https://github.com/fnproject/fn/blob/master/docs/developers/function-format.md.
+package protocol