diff --git a/pkg/api/helper.go b/pkg/api/helper.go
index 2d031d83ddd..df11cc39c40 100644
--- a/pkg/api/helper.go
+++ b/pkg/api/helper.go
@@ -42,6 +42,8 @@ func init() {
 	)
 }
 
+// AddKnownTypes registers the types of the arguments to the marshaller of the package api.
+// Encode() refuses the object unless its type is registered with AddKnownTypes.
 func AddKnownTypes(types ...interface{}) {
 	for _, obj := range types {
 		t := reflect.TypeOf(obj)
@@ -49,14 +51,14 @@ func AddKnownTypes(types ...interface{}) {
 	}
 }
 
-// Takes an arbitary api type, returns pointer to its JSONBase field.
+// FindJSONBase takes an arbitary api type, returns pointer to its JSONBase field.
 // obj must be a pointer to an api type.
 func FindJSONBase(obj interface{}) (*JSONBase, error) {
 	_, jsonBase, err := nameAndJSONBase(obj)
 	return jsonBase, err
 }
 
-// Takes an arbitary api type, return a copy of its JSONBase field.
+// FindJSONBaseRO takes an arbitary api type, return a copy of its JSONBase field.
 // obj may be a pointer to an api type, or a non-pointer struct api type.
 func FindJSONBaseRO(obj interface{}) (JSONBase, error) {
 	v := reflect.ValueOf(obj)
@@ -141,7 +143,7 @@ func Decode(data []byte) (interface{}, error) {
 	// yaml is a superset of json, so we use it to decode here. That way, we understand both.
 	err := yaml.Unmarshal(data, &findKind)
 	if err != nil {
-		return nil, fmt.Errorf("Couldn't get kind: %#v", err)
+		return nil, fmt.Errorf("couldn't get kind: %#v", err)
 	}
 	objType, found := knownTypes[findKind.Kind]
 	if !found {
diff --git a/pkg/api/types.go b/pkg/api/types.go
index 4627481e8ac..92b91adc488 100644
--- a/pkg/api/types.go
+++ b/pkg/api/types.go
@@ -153,8 +153,10 @@ type JSONBase struct {
 	ResourceVersion   uint64 `json:"resourceVersion,omitempty" yaml:"resourceVersion,omitempty"`
 }
 
+// PodStatus represents a status of a pod.
 type PodStatus string
 
+// These are the valid statuses of pods.
 const (
 	PodRunning PodStatus = "Running"
 	PodPending PodStatus = "Pending"
@@ -179,6 +181,7 @@ type PodState struct {
 	Info PodInfo `json:"info,omitempty" yaml:"info,omitempty"`
 }
 
+// PodList is a list of Pods.
 type PodList struct {
 	JSONBase `json:",inline" yaml:",inline"`
 	Items    []Pod `json:"items" yaml:"items,omitempty"`
@@ -199,6 +202,7 @@ type ReplicationControllerState struct {
 	PodTemplate     PodTemplate       `json:"podTemplate,omitempty" yaml:"podTemplate,omitempty"`
 }
 
+// ReplicationControllerList is a collection of replication controllers.
 type ReplicationControllerList struct {
 	JSONBase `json:",inline" yaml:",inline"`
 	Items    []ReplicationController `json:"items,omitempty" yaml:"items,omitempty"`
@@ -223,7 +227,7 @@ type ServiceList struct {
 	Items    []Service `json:"items" yaml:"items"`
 }
 
-// Defines a service abstraction by a name (for example, mysql) consisting of local port
+// Service is a named abstraction of software service (for example, mysql) consisting of local port
 // (for example 3306) that the proxy listens on, and the selector that determines which pods
 // will answer requests sent through the proxy.
 type Service struct {
@@ -238,22 +242,22 @@ type Service struct {
 	CreateExternalLoadBalancer bool              `json:"createExternalLoadBalancer,omitempty" yaml:"createExternalLoadBalancer,omitempty"`
 }
 
-// Defines the endpoints that implement the actual service, for example:
+// Endpoints is a collection of endpoints that implement the actual service, for example:
 // Name: "mysql", Endpoints: ["10.10.1.1:1909", "10.10.2.2:8834"]
 type Endpoints struct {
 	Name      string
 	Endpoints []string
 }
 
-// Information about a single Minion; the name of the minion according to etcd
-// is in JSONBase.ID.
+// Minion is a worker node in Kubernetenes.
+// The name of the minion according to etcd is in JSONBase.ID.
 type Minion struct {
 	JSONBase `json:",inline" yaml:",inline"`
 	// Queried from cloud provider, if available.
 	HostIP string `json:"hostIP,omitempty" yaml:"hostIP,omitempty"`
 }
 
-// A list of minions.
+// MinionList is a list of minions.
 type MinionList struct {
 	JSONBase `json:",inline" yaml:",inline"`
 	Items    []Minion `json:"minions,omitempty" yaml:"minions,omitempty"`
@@ -282,12 +286,12 @@ const (
 	StatusWorking = "working"
 )
 
-// Operation information, as delivered to API clients.
+// ServerOp is an operation delivered to API clients.
 type ServerOp struct {
 	JSONBase `yaml:",inline" json:",inline"`
 }
 
-// Operation list, as delivered to API clients.
+// ServerOpList is a list of operations, as delivered to API clients.
 type ServerOpList struct {
 	JSONBase `yaml:",inline" json:",inline"`
 	Items    []ServerOp `yaml:"items,omitempty" json:"items,omitempty"`
diff --git a/pkg/api/validation.go b/pkg/api/validation.go
index 278604602eb..ded4b96bbd6 100644
--- a/pkg/api/validation.go
+++ b/pkg/api/validation.go
@@ -24,19 +24,20 @@ import (
 )
 
 var (
-	supportedManifestVersions util.StringSet = util.NewStringSet("v1beta1", "v1beta2")
+	supportedManifestVersions = util.NewStringSet("v1beta1", "v1beta2")
 )
 
-// Validation errors.
+// ValidationErrorEnum is a type of validation error.
 type ValidationErrorEnum string
 
+// These are known errors of validation.
 const (
 	ErrTypeInvalid      ValidationErrorEnum = "invalid value"
 	ErrTypeNotSupported ValidationErrorEnum = "unsupported value"
 	ErrTypeDuplicate    ValidationErrorEnum = "duplicate value"
 )
 
-// Implements the 'error' interface.
+// ValidationError is an implementation of the 'error' interface, which represents an error of validation.
 type ValidationError struct {
 	ErrorType  ValidationErrorEnum
 	ErrorField string