Add some documentation

pkg/api/types.go

@@ -26,10 +26,12 @@ type ContainerManifest struct {
 	Id         string      `yaml:"id,omitempty" json:"id,omitempty"`
 }
 
+// Volume represents a named volume in a pod that may be accessed by any containers in the pod.
 type Volume struct {
 	Name string `yaml:"name" json:"name"`
 }
 
+// Port represents a network port in a single container
 type Port struct {
 	Name          string `yaml:"name,omitempty" json:"name,omitempty"`
 	HostPort      int    `yaml:"hostPort,omitempty" json:"hostPort,omitempty"`
@@ -37,12 +39,15 @@ type Port struct {
 	Protocol      string `yaml:"protocol,omitempty" json:"protocol,omitempty"`
 }
 
+// VolumeMount describes a mounting of a Volume within a container
 type VolumeMount struct {
+	// Name must match the Name of a volume [above]
 	Name      string `yaml:"name,omitempty" json:"name,omitempty"`
 	ReadOnly  bool   `yaml:"readOnly,omitempty" json:"readOnly,omitempty"`
 	MountPath string `yaml:"mountPath,omitempty" json:"mountPath,omitempty"`
 }
 
+// EnvVar represents an environment variable present in a Container
 type EnvVar struct {
 	Name  string `yaml:"name,omitempty" json:"name,omitempty"`
 	Value string `yaml:"value,omitempty" json:"value,omitempty"`

pkg/apiserver/api_server.go

@@ -13,6 +13,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
+
 package apiserver
 
 import (
@@ -131,6 +132,15 @@ func (server *ApiServer) readBody(req *http.Request) (string, error) {
 	return string(body), err
 }
 
+// handleREST is the main dispatcher for the server.  It switches on the HTTP method, and then
+// on path length, according to the following table:
+//   Method     Path          Action
+//   GET        /foo          list
+//   GET        /foo/bar      get 'bar'
+//   POST       /foo          create
+//   PUT        /foo/bar      update 'bar'
+//   DELETE     /foo/bar      delete 'bar'
+// Returns 404 if the method/pattern doesn't match one of these entries
 func (server *ApiServer) handleREST(parts []string, url *url.URL, req *http.Request, w http.ResponseWriter, storage RESTStorage) {
 	switch req.Method {
 	case "GET":

pkg/client/client.go

@@ -112,6 +112,8 @@ func (client Client) makeURL(path string) string {
 	return client.Host + "/api/v1beta1/" + path
 }
 
+// EncodeLabelQuery transforms a label query expressed as a key/value map, into a
+// comma separated, key=value encoding.
 func EncodeLabelQuery(labelQuery map[string]string) string {
 	query := make([]string, 0, len(labelQuery))
 	for key, value := range labelQuery {
@@ -120,6 +122,8 @@ func EncodeLabelQuery(labelQuery map[string]string) string {
 	return url.QueryEscape(strings.Join(query, ","))
 }
 
+// DecodeLabelQuery transforms a label query from a comma separated, key=value format into
+// a key/value map.
 func DecodeLabelQuery(labelQuery string) map[string]string {
 	result := map[string]string{}
 	if len(labelQuery) == 0 {

pkg/client/container_info.go

@@ -23,10 +23,15 @@ import (
 	"net/http"
 )
 
+// ContainerInfo is an interface for things that can get information about a container.
+// Injectable for easy testing.
 type ContainerInfo interface {
+	// GetContainerInfo returns information about container 'name' on 'host'
+	// Returns an untyped interface, and an error, if one occurs
 	GetContainerInfo(host, name string) (interface{}, error)
 }
 
+// The default implementation, accesses the kubelet over HTTP
 type HTTPContainerInfo struct {
 	Client *http.Client
 	Port   uint