Update API doc for Storage v1alpha1, v1beta1 types and Discovery v1 types

staging/src/k8s.io/api/discovery/v1/types.go

@@ -29,9 +29,11 @@ import (
 // labels, which must be joined to produce the full set of endpoints.
 type EndpointSlice struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata.
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+	
 	// addressType specifies the type of address carried by this EndpointSlice.
 	// All addresses in this slice must be the same type. This field is
 	// immutable after creation. The following address types are currently
@@ -40,10 +42,12 @@ type EndpointSlice struct {
 	// * IPv6: Represents an IPv6 Address.
 	// * FQDN: Represents a Fully Qualified Domain Name.
 	AddressType AddressType `json:"addressType" protobuf:"bytes,4,rep,name=addressType"`
+	
 	// endpoints is a list of unique endpoints in this slice. Each slice may
 	// include a maximum of 1000 endpoints.
 	// +listType=atomic
 	Endpoints []Endpoint `json:"endpoints" protobuf:"bytes,2,rep,name=endpoints"`
+	
 	// ports specifies the list of network ports exposed by each endpoint in
 	// this slice. Each port must have a unique name. When ports is empty, it
 	// indicates that there are no defined ports. When a port is defined with a
@@ -61,8 +65,10 @@ type AddressType string
 const (
 	// AddressTypeIPv4 represents an IPv4 Address.
 	AddressTypeIPv4 = AddressType(v1.IPv4Protocol)
+	
 	// AddressTypeIPv6 represents an IPv6 Address.
 	AddressTypeIPv6 = AddressType(v1.IPv6Protocol)
+	
 	// AddressTypeFQDN represents a FQDN.
 	AddressTypeFQDN = AddressType("FQDN")
 )
@@ -77,8 +83,10 @@ type Endpoint struct {
 	// use the first element. Refer to: https://issue.k8s.io/106267
 	// +listType=set
 	Addresses []string `json:"addresses" protobuf:"bytes,1,rep,name=addresses"`
+	
 	// conditions contains information about the current status of the endpoint.
 	Conditions EndpointConditions `json:"conditions,omitempty" protobuf:"bytes,2,opt,name=conditions"`
+	
 	// hostname of this endpoint. This field may be used by consumers of
 	// endpoints to distinguish endpoints from each other (e.g. in DNS names).
 	// Multiple endpoints which use the same hostname should be considered
@@ -86,6 +94,7 @@ type Endpoint struct {
 	// Label (RFC 1123) validation.
 	// +optional
 	Hostname *string `json:"hostname,omitempty" protobuf:"bytes,3,opt,name=hostname"`
+	
 	// targetRef is a reference to a Kubernetes object that represents this
 	// endpoint.
 	// +optional
@@ -104,9 +113,11 @@ type Endpoint struct {
 	// be used to determine endpoints local to a Node.
 	// +optional
 	NodeName *string `json:"nodeName,omitempty" protobuf:"bytes,6,opt,name=nodeName"`
+	
 	// zone is the name of the Zone this endpoint exists in.
 	// +optional
 	Zone *string `json:"zone,omitempty" protobuf:"bytes,7,opt,name=zone"`
+	
 	// hints contains information associated with how an endpoint should be
 	// consumed.
 	// +optional
@@ -154,24 +165,26 @@ type ForZone struct {
 // EndpointPort represents a Port used by an EndpointSlice
 // +structType=atomic
 type EndpointPort struct {
-	// The name of this port. All ports in an EndpointSlice must have a unique
+	// name represents the name of this port. All ports in an EndpointSlice must have a unique name.
-	// name. If the EndpointSlice is dervied from a Kubernetes service, this
+	// If the EndpointSlice is dervied from a Kubernetes service, this corresponds to the Service.ports[].name.
-	// corresponds to the Service.ports[].name.
 	// Name must either be an empty string or pass DNS_LABEL validation:
 	// * must be no more than 63 characters long.
 	// * must consist of lower case alphanumeric characters or '-'.
 	// * must start and end with an alphanumeric character.
 	// Default is empty string.
 	Name *string `json:"name,omitempty" protobuf:"bytes,1,name=name"`
-	// The IP protocol for this port.
+	
+	// protocol represents the IP protocol for this port.
 	// Must be UDP, TCP, or SCTP.
 	// Default is TCP.
 	Protocol *v1.Protocol `json:"protocol,omitempty" protobuf:"bytes,2,name=protocol"`
-	// The port number of the endpoint.
+	
+	// port represents the port number of the endpoint.
 	// If this is not specified, ports are not restricted and must be
 	// interpreted in the context of the specific consumer.
 	Port *int32 `json:"port,omitempty" protobuf:"bytes,3,opt,name=port"`
-	// The application protocol for this port.
+	
+	// appProtocol represents the application protocol for this port.
 	// This field follows standard Kubernetes label syntax.
 	// Un-prefixed names are reserved for IANA standard service names (as per
 	// RFC-6335 and https://www.iana.org/assignments/service-names).
@@ -186,9 +199,11 @@ type EndpointPort struct {
 // EndpointSliceList represents a list of endpoint slices
 type EndpointSliceList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata.
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
-	// List of endpoint slices
+	
+	// items is the list of endpoint slices
 	Items []EndpointSlice `json:"items" protobuf:"bytes,2,rep,name=items"`
 }

staging/src/k8s.io/api/discovery/v1beta1/types.go

@@ -33,9 +33,11 @@ import (
 // labels, which must be joined to produce the full set of endpoints.
 type EndpointSlice struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata.
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+	
 	// addressType specifies the type of address carried by this EndpointSlice.
 	// All addresses in this slice must be the same type. This field is
 	// immutable after creation. The following address types are currently
@@ -44,10 +46,12 @@ type EndpointSlice struct {
 	// * IPv6: Represents an IPv6 Address.
 	// * FQDN: Represents a Fully Qualified Domain Name.
 	AddressType AddressType `json:"addressType" protobuf:"bytes,4,rep,name=addressType"`
+	
 	// endpoints is a list of unique endpoints in this slice. Each slice may
 	// include a maximum of 1000 endpoints.
 	// +listType=atomic
 	Endpoints []Endpoint `json:"endpoints" protobuf:"bytes,2,rep,name=endpoints"`
+	
 	// ports specifies the list of network ports exposed by each endpoint in
 	// this slice. Each port must have a unique name. When ports is empty, it
 	// indicates that there are no defined ports. When a port is defined with a
@@ -64,8 +68,10 @@ type AddressType string
 const (
 	// AddressTypeIPv4 represents an IPv4 Address.
 	AddressTypeIPv4 = AddressType(v1.IPv4Protocol)
+	
 	// AddressTypeIPv6 represents an IPv6 Address.
 	AddressTypeIPv6 = AddressType(v1.IPv6Protocol)
+	
 	// AddressTypeFQDN represents a FQDN.
 	AddressTypeFQDN = AddressType("FQDN")
 )
@@ -80,8 +86,10 @@ type Endpoint struct {
 	// use the first element. Refer to: https://issue.k8s.io/106267
 	// +listType=set
 	Addresses []string `json:"addresses" protobuf:"bytes,1,rep,name=addresses"`
+	
 	// conditions contains information about the current status of the endpoint.
 	Conditions EndpointConditions `json:"conditions,omitempty" protobuf:"bytes,2,opt,name=conditions"`
+	
 	// hostname of this endpoint. This field may be used by consumers of
 	// endpoints to distinguish endpoints from each other (e.g. in DNS names).
 	// Multiple endpoints which use the same hostname should be considered
@@ -89,10 +97,12 @@ type Endpoint struct {
 	// Label (RFC 1123) validation.
 	// +optional
 	Hostname *string `json:"hostname,omitempty" protobuf:"bytes,3,opt,name=hostname"`
+	
 	// targetRef is a reference to a Kubernetes object that represents this
 	// endpoint.
 	// +optional
 	TargetRef *v1.ObjectReference `json:"targetRef,omitempty" protobuf:"bytes,4,opt,name=targetRef"`
+	
 	// topology contains arbitrary topology information associated with the
 	// endpoint. These key/value pairs must conform with the label format.
 	// https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
@@ -108,10 +118,12 @@ type Endpoint struct {
 	// This field is deprecated and will be removed in future api versions.
 	// +optional
 	Topology map[string]string `json:"topology,omitempty" protobuf:"bytes,5,opt,name=topology"`
+	
 	// nodeName represents the name of the Node hosting this endpoint. This can
 	// be used to determine endpoints local to a Node.
 	// +optional
 	NodeName *string `json:"nodeName,omitempty" protobuf:"bytes,6,opt,name=nodeName"`
+	
 	// hints contains information associated with how an endpoint should be
 	// consumed.
 	// +featureGate=TopologyAwareHints
@@ -159,23 +171,25 @@ type ForZone struct {
 
 // EndpointPort represents a Port used by an EndpointSlice
 type EndpointPort struct {
-	// The name of this port. All ports in an EndpointSlice must have a unique
+	// name represents the name of this port. All ports in an EndpointSlice must have a unique name.
-	// name. If the EndpointSlice is dervied from a Kubernetes service, this
+	// If the EndpointSlice is dervied from a Kubernetes service, this corresponds to the Service.ports[].name.
-	// corresponds to the Service.ports[].name.
 	// Name must either be an empty string or pass DNS_LABEL validation:
 	// * must be no more than 63 characters long.
 	// * must consist of lower case alphanumeric characters or '-'.
 	// * must start and end with an alphanumeric character.
 	// Default is empty string.
 	Name *string `json:"name,omitempty" protobuf:"bytes,1,name=name"`
+	
 	// protocol represents the IP protocol for this port.
 	// Must be UDP, TCP, or SCTP.
 	// Default is TCP.
 	Protocol *v1.Protocol `json:"protocol,omitempty" protobuf:"bytes,2,name=protocol"`
+	
 	// port represents the port number of the endpoint.
 	// If this is not specified, ports are not restricted and must be
 	// interpreted in the context of the specific consumer.
 	Port *int32 `json:"port,omitempty" protobuf:"bytes,3,opt,name=port"`
+	
 	// appProtocol represents the application protocol for this port.
 	// This field follows standard Kubernetes label syntax.
 	// Un-prefixed names are reserved for IANA standard service names (as per
@@ -195,9 +209,11 @@ type EndpointPort struct {
 // EndpointSliceList represents a list of endpoint slices
 type EndpointSliceList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata.
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+	
 	// items is the list of endpoint slices
 	Items []EndpointSlice `json:"items" protobuf:"bytes,2,rep,name=items"`
 }

staging/src/k8s.io/api/storage/v1/types.go

@@ -33,6 +33,7 @@ import (
 // according to etcd is in ObjectMeta.Name.
 type StorageClass struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata.
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
@@ -46,14 +47,13 @@ type StorageClass struct {
 	// +optional
 	Parameters map[string]string `json:"parameters,omitempty" protobuf:"bytes,3,rep,name=parameters"`
 
-	// Dynamically provisioned PersistentVolumes of this storage class are
+	// reclaimPolicy controls the reclaimPolicy for dynamically provisioned PersistentVolumes of this storage class.
-	// created with this reclaimPolicy.
 	// Defaults to Delete.
 	// +optional
 	ReclaimPolicy *v1.PersistentVolumeReclaimPolicy `json:"reclaimPolicy,omitempty" protobuf:"bytes,4,opt,name=reclaimPolicy,casttype=k8s.io/api/core/v1.PersistentVolumeReclaimPolicy"`
 
-	// Dynamically provisioned PersistentVolumes of this storage class are
+	// mountOptions controls the mountOptions for dynamically provisioned PersistentVolumes of this storage class.
-	// created with these mountOptions, e.g. ["ro", "soft"]. Not validated -
+	// e.g. ["ro", "soft"]. Not validated -
 	// mount of the PVs will simply fail if one is invalid.
 	// +optional
 	MountOptions []string `json:"mountOptions,omitempty" protobuf:"bytes,5,opt,name=mountOptions"`
@@ -82,6 +82,7 @@ type StorageClass struct {
 // StorageClassList is a collection of storage classes.
 type StorageClassList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
@@ -127,7 +128,7 @@ type VolumeAttachment struct {
 	// Populated by the Kubernetes system.
 	Spec VolumeAttachmentSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
 
-	// status of the VolumeAttachment request.
+	// status represents status of the VolumeAttachment request.
 	// Populated by the entity completing the attach or detach
 	// operation, i.e. the external-attacher.
 	// +optional
@@ -139,6 +140,7 @@ type VolumeAttachment struct {
 // VolumeAttachmentList is a collection of VolumeAttachment objects.
 type VolumeAttachmentList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
@@ -210,7 +212,7 @@ type VolumeAttachmentStatus struct {
 
 // VolumeError captures an error encountered during a volume operation.
 type VolumeError struct {
-	// time the error was encountered.
+	// time represents the time the error was encountered.
 	// +optional
 	Time metav1.Time `json:"time,omitempty" protobuf:"bytes,1,opt,name=time"`
 
@@ -280,16 +282,15 @@ type CSIDriverSpec struct {
 	// +optional
 	AttachRequired *bool `json:"attachRequired,omitempty" protobuf:"varint,1,opt,name=attachRequired"`
 
-	// If set to true, podInfoOnMount indicates this CSI volume driver
+	// podInfoOnMount indicates this CSI volume driver requires additional pod information (like podName, podUID, etc.) 
-	// requires additional pod information (like podName, podUID, etc.) during
+	// during mount operations, if set to true.
-	// mount operations.
 	// If set to false, pod information will not be passed on mount.
 	// Default is false.
+	//
 	// The CSI driver specifies podInfoOnMount as part of driver deployment.
-	// If true, Kubelet will pass pod information as VolumeContext in the CSI
+	// If true, Kubelet will pass pod information as VolumeContext in the CSI NodePublishVolume() calls.
-	// NodePublishVolume() calls.
+	// The CSI driver is responsible for parsing and validating the information passed in as VolumeContext.
-	// The CSI driver is responsible for parsing and validating the information
+	//
-	// passed in as VolumeContext.
 	// The following VolumeConext will be passed if podInfoOnMount is set to true.
 	// This list might grow, but the prefix will be used.
 	// "csi.storage.k8s.io/pod.name": pod.Name
@@ -311,29 +312,27 @@ type CSIDriverSpec struct {
 	PodInfoOnMount *bool `json:"podInfoOnMount,omitempty" protobuf:"bytes,2,opt,name=podInfoOnMount"`
 
 	// volumeLifecycleModes defines what kind of volumes this CSI volume driver supports.
-	// The default if the list is empty is "Persistent", which is the usage
+	// The default if the list is empty is "Persistent", which is the usage defined by the 
-	// defined by the CSI specification and implemented in Kubernetes via the usual
+	// CSI specification and implemented in Kubernetes via the usual PV/PVC mechanism.
-	// PV/PVC mechanism.
+	//
-	// The other mode is "Ephemeral". In this mode, volumes are defined inline
+	// The other mode is "Ephemeral". In this mode, volumes are defined inline inside the pod spec 
-	// inside the pod spec with CSIVolumeSource and their lifecycle is tied to
+	// with CSIVolumeSource and their lifecycle is tied to the lifecycle of that pod.
-	// the lifecycle of that pod. A driver has to be aware of this
+	// A driver has to be aware of this because it is only going to get a NodePublishVolume call for such a volume.
-	// because it is only going to get a NodePublishVolume call for such a volume.
+	//
 	// For more information about implementing this mode, see
 	// https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html
-	// A driver can support one or more of these modes and
+	// A driver can support one or more of these modes and more modes may be added in the future.
-	// more modes may be added in the future.
-	// This field is beta.
 	//
+	// This field is beta.
 	// This field is immutable.
 	//
 	// +optional
 	// +listType=set
 	VolumeLifecycleModes []VolumeLifecycleMode `json:"volumeLifecycleModes,omitempty" protobuf:"bytes,3,opt,name=volumeLifecycleModes"`
 
-	// If set to true, storageCapacity indicates that the CSI
+	// storageCapacity indicates that the CSI volume driver wants pod scheduling to consider the storage
-	// volume driver wants pod scheduling to consider the storage
 	// capacity that the driver deployment will report by creating
-	// CSIStorageCapacity objects with capacity information.
+	// CSIStorageCapacity objects with capacity information, if set to true.
 	//
 	// The check can be enabled immediately when deploying a driver.
 	// In that case, provisioning new volumes with late binding
@@ -360,6 +359,7 @@ type CSIDriverSpec struct {
 	// to determine if Kubernetes should modify ownership and permissions of the volume.
 	// With the default policy the defined fsGroup will only be applied
 	// if a fstype is defined and the volume's access mode contains ReadWriteOnce.
+	//
 	// +optional
 	FSGroupPolicy *FSGroupPolicy `json:"fsGroupPolicy,omitempty" protobuf:"bytes,5,opt,name=fsGroupPolicy"`
 
@@ -610,6 +610,7 @@ type CSINodeList struct {
 // node.
 type CSIStorageCapacity struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata.
 	// The name has no particular meaning. It must be a DNS subdomain (dots allowed, 253 characters).
 	// To ensure that there are no conflicts with other CSI drivers on the cluster,
@@ -671,6 +672,7 @@ type CSIStorageCapacity struct {
 // CSIStorageCapacityList is a collection of CSIStorageCapacity objects.
 type CSIStorageCapacityList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional

staging/src/k8s.io/api/storage/v1alpha1/types.go

@@ -41,11 +41,11 @@ type VolumeAttachment struct {
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Specification of the desired attach/detach volume behavior.
+	// spec represents specification of the desired attach/detach volume behavior.
 	// Populated by the Kubernetes system.
 	Spec VolumeAttachmentSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
 
-	// Status of the VolumeAttachment request.
+	// status represents status of the VolumeAttachment request.
 	// Populated by the entity completing the attach or detach
 	// operation, i.e. the external-attacher.
 	// +optional
@@ -60,25 +60,26 @@ type VolumeAttachment struct {
 // VolumeAttachmentList is a collection of VolumeAttachment objects.
 type VolumeAttachmentList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Items is the list of VolumeAttachments
+	// items is the list of VolumeAttachments
 	Items []VolumeAttachment `json:"items" protobuf:"bytes,2,rep,name=items"`
 }
 
 // VolumeAttachmentSpec is the specification of a VolumeAttachment request.
 type VolumeAttachmentSpec struct {
-	// Attacher indicates the name of the volume driver that MUST handle this
+	// attacher indicates the name of the volume driver that MUST handle this
 	// request. This is the name returned by GetPluginName().
 	Attacher string `json:"attacher" protobuf:"bytes,1,opt,name=attacher"`
 
-	// Source represents the volume that should be attached.
+	// source represents the volume that should be attached.
 	Source VolumeAttachmentSource `json:"source" protobuf:"bytes,2,opt,name=source"`
 
-	// The node that the volume should be attached to.
+	// nodeName represents the node that the volume should be attached to.
 	NodeName string `json:"nodeName" protobuf:"bytes,3,opt,name=nodeName"`
 }
 
@@ -87,7 +88,7 @@ type VolumeAttachmentSpec struct {
 // in future we may allow also inline volumes in pods.
 // Exactly one member can be set.
 type VolumeAttachmentSource struct {
-	// Name of the persistent volume to attach.
+	// persistentVolumeName represents the name of the persistent volume to attach.
 	// +optional
 	PersistentVolumeName *string `json:"persistentVolumeName,omitempty" protobuf:"bytes,1,opt,name=persistentVolumeName"`
 
@@ -103,26 +104,26 @@ type VolumeAttachmentSource struct {
 
 // VolumeAttachmentStatus is the status of a VolumeAttachment request.
 type VolumeAttachmentStatus struct {
-	// Indicates the volume is successfully attached.
+	// attached indicates the volume is successfully attached.
 	// This field must only be set by the entity completing the attach
 	// operation, i.e. the external-attacher.
 	Attached bool `json:"attached" protobuf:"varint,1,opt,name=attached"`
 
-	// Upon successful attach, this field is populated with any
+	// attachmentMetadata is populated with any
-	// information returned by the attach operation that must be passed
+	// information returned by the attach operation, upon successful attach, that must be passed
 	// into subsequent WaitForAttach or Mount calls.
 	// This field must only be set by the entity completing the attach
 	// operation, i.e. the external-attacher.
 	// +optional
 	AttachmentMetadata map[string]string `json:"attachmentMetadata,omitempty" protobuf:"bytes,2,rep,name=attachmentMetadata"`
 
-	// The last error encountered during attach operation, if any.
+	// attachError represents the last error encountered during attach operation, if any.
 	// This field must only be set by the entity completing the attach
 	// operation, i.e. the external-attacher.
 	// +optional
 	AttachError *VolumeError `json:"attachError,omitempty" protobuf:"bytes,3,opt,name=attachError,casttype=VolumeError"`
 
-	// The last error encountered during detach operation, if any.
+	// detachError represents the last error encountered during detach operation, if any.
 	// This field must only be set by the entity completing the detach
 	// operation, i.e. the external-attacher.
 	// +optional
@@ -131,11 +132,11 @@ type VolumeAttachmentStatus struct {
 
 // VolumeError captures an error encountered during a volume operation.
 type VolumeError struct {
-	// Time the error was encountered.
+	// time represents the time the error was encountered.
 	// +optional
 	Time metav1.Time `json:"time,omitempty" protobuf:"bytes,1,opt,name=time"`
 
-	// String detailing the error encountered during Attach or Detach operation.
+	// message represents the error encountered during Attach or Detach operation.
 	// This string maybe logged, so it should not contain sensitive
 	// information.
 	// +optional
@@ -174,6 +175,7 @@ type VolumeError struct {
 // node.
 type CSIStorageCapacity struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata. The name has no particular meaning. It must be
 	// be a DNS subdomain (dots allowed, 253 characters). To ensure that
 	// there are no conflicts with other CSI drivers on the cluster, the recommendation
@@ -186,7 +188,7 @@ type CSIStorageCapacity struct {
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// NodeTopology defines which nodes have access to the storage
+	// nodeTopology defines which nodes have access to the storage
 	// for which capacity was reported. If not set, the storage is
 	// not accessible from any node in the cluster. If empty, the
 	// storage is accessible from all nodes. This field is
@@ -195,7 +197,7 @@ type CSIStorageCapacity struct {
 	// +optional
 	NodeTopology *metav1.LabelSelector `json:"nodeTopology,omitempty" protobuf:"bytes,2,opt,name=nodeTopology"`
 
-	// The name of the StorageClass that the reported capacity applies to.
+	// storageClassName represents the name of the StorageClass that the reported capacity applies to.
 	// It must meet the same requirements as the name of a StorageClass
 	// object (non-empty, DNS subdomain). If that object no longer exists,
 	// the CSIStorageCapacity object is obsolete and should be removed by its
@@ -203,7 +205,7 @@ type CSIStorageCapacity struct {
 	// This field is immutable.
 	StorageClassName string `json:"storageClassName" protobuf:"bytes,3,name=storageClassName"`
 
-	// Capacity is the value reported by the CSI driver in its GetCapacityResponse
+	// capacity is the value reported by the CSI driver in its GetCapacityResponse
 	// for a GetCapacityRequest with topology and parameters that match the
 	// previous fields.
 	//
@@ -215,7 +217,7 @@ type CSIStorageCapacity struct {
 	// +optional
 	Capacity *resource.Quantity `json:"capacity,omitempty" protobuf:"bytes,4,opt,name=capacity"`
 
-	// MaximumVolumeSize is the value reported by the CSI driver in its GetCapacityResponse
+	// maximumVolumeSize is the value reported by the CSI driver in its GetCapacityResponse
 	// for a GetCapacityRequest with topology and parameters that match the
 	// previous fields.
 	//
@@ -238,12 +240,13 @@ type CSIStorageCapacity struct {
 // CSIStorageCapacityList is a collection of CSIStorageCapacity objects.
 type CSIStorageCapacityList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Items is the list of CSIStorageCapacity objects.
+	// items is the list of CSIStorageCapacity objects.
 	// +listType=map
 	// +listMapKey=name
 	Items []CSIStorageCapacity `json:"items" protobuf:"bytes,2,rep,name=items"`

staging/src/k8s.io/api/storage/v1beta1/types.go

@@ -36,41 +36,42 @@ import (
 // according to etcd is in ObjectMeta.Name.
 type StorageClass struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata.
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Provisioner indicates the type of the provisioner.
+	// provisioner indicates the type of the provisioner.
 	Provisioner string `json:"provisioner" protobuf:"bytes,2,opt,name=provisioner"`
 
-	// Parameters holds the parameters for the provisioner that should
+	// parameters holds the parameters for the provisioner that should
 	// create volumes of this storage class.
 	// +optional
 	Parameters map[string]string `json:"parameters,omitempty" protobuf:"bytes,3,rep,name=parameters"`
 
-	// Dynamically provisioned PersistentVolumes of this storage class are
+	// reclaimPolicy controls the reclaimPolicy for dynamically provisioned PersistentVolumes of this storage class.
-	// created with this reclaimPolicy. Defaults to Delete.
+	// Defaults to Delete.
 	// +optional
 	ReclaimPolicy *v1.PersistentVolumeReclaimPolicy `json:"reclaimPolicy,omitempty" protobuf:"bytes,4,opt,name=reclaimPolicy,casttype=k8s.io/api/core/v1.PersistentVolumeReclaimPolicy"`
 
-	// Dynamically provisioned PersistentVolumes of this storage class are
+	// mountOptions controls the mountOptions for dynamically provisioned PersistentVolumes of this storage class.
-	// created with these mountOptions, e.g. ["ro", "soft"]. Not validated -
+	// e.g. ["ro", "soft"]. Not validated -
 	// mount of the PVs will simply fail if one is invalid.
 	// +optional
 	MountOptions []string `json:"mountOptions,omitempty" protobuf:"bytes,5,opt,name=mountOptions"`
 
-	// AllowVolumeExpansion shows whether the storage class allow volume expand
+	// allowVolumeExpansion shows whether the storage class allow volume expand
 	// +optional
 	AllowVolumeExpansion *bool `json:"allowVolumeExpansion,omitempty" protobuf:"varint,6,opt,name=allowVolumeExpansion"`
 
-	// VolumeBindingMode indicates how PersistentVolumeClaims should be
+	// volumeBindingMode indicates how PersistentVolumeClaims should be
 	// provisioned and bound.  When unset, VolumeBindingImmediate is used.
 	// This field is only honored by servers that enable the VolumeScheduling feature.
 	// +optional
 	VolumeBindingMode *VolumeBindingMode `json:"volumeBindingMode,omitempty" protobuf:"bytes,7,opt,name=volumeBindingMode"`
 
-	// Restrict the node topologies where volumes can be dynamically provisioned.
+	// allowedTopologies restrict the node topologies where volumes can be dynamically provisioned.
 	// Each volume plugin defines its own supported topology specifications.
 	// An empty TopologySelectorTerm list means there is no topology restriction.
 	// This field is only honored by servers that enable the VolumeScheduling feature.
@@ -87,12 +88,13 @@ type StorageClass struct {
 // StorageClassList is a collection of storage classes.
 type StorageClassList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Items is the list of StorageClasses
+	// items is the list of StorageClasses
 	Items []StorageClass `json:"items" protobuf:"bytes,2,rep,name=items"`
 }
 
@@ -130,11 +132,11 @@ type VolumeAttachment struct {
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Specification of the desired attach/detach volume behavior.
+	// spec represents specification of the desired attach/detach volume behavior.
 	// Populated by the Kubernetes system.
 	Spec VolumeAttachmentSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
 
-	// Status of the VolumeAttachment request.
+	// status represents status of the VolumeAttachment request.
 	// Populated by the entity completing the attach or detach
 	// operation, i.e. the external-attacher.
 	// +optional
@@ -149,25 +151,26 @@ type VolumeAttachment struct {
 // VolumeAttachmentList is a collection of VolumeAttachment objects.
 type VolumeAttachmentList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Items is the list of VolumeAttachments
+	// items is the list of VolumeAttachments
 	Items []VolumeAttachment `json:"items" protobuf:"bytes,2,rep,name=items"`
 }
 
 // VolumeAttachmentSpec is the specification of a VolumeAttachment request.
 type VolumeAttachmentSpec struct {
-	// Attacher indicates the name of the volume driver that MUST handle this
+	// attacher indicates the name of the volume driver that MUST handle this
 	// request. This is the name returned by GetPluginName().
 	Attacher string `json:"attacher" protobuf:"bytes,1,opt,name=attacher"`
 
-	// Source represents the volume that should be attached.
+	// source represents the volume that should be attached.
 	Source VolumeAttachmentSource `json:"source" protobuf:"bytes,2,opt,name=source"`
 
-	// The node that the volume should be attached to.
+	// nodeName represents the node that the volume should be attached to.
 	NodeName string `json:"nodeName" protobuf:"bytes,3,opt,name=nodeName"`
 }
 
@@ -176,7 +179,7 @@ type VolumeAttachmentSpec struct {
 // in future we may allow also inline volumes in pods.
 // Exactly one member can be set.
 type VolumeAttachmentSource struct {
-	// Name of the persistent volume to attach.
+	// persistentVolumeName represents the name of the persistent volume to attach.
 	// +optional
 	PersistentVolumeName *string `json:"persistentVolumeName,omitempty" protobuf:"bytes,1,opt,name=persistentVolumeName"`
 
@@ -192,26 +195,26 @@ type VolumeAttachmentSource struct {
 
 // VolumeAttachmentStatus is the status of a VolumeAttachment request.
 type VolumeAttachmentStatus struct {
-	// Indicates the volume is successfully attached.
+	// attached indicates the volume is successfully attached.
 	// This field must only be set by the entity completing the attach
 	// operation, i.e. the external-attacher.
 	Attached bool `json:"attached" protobuf:"varint,1,opt,name=attached"`
 
-	// Upon successful attach, this field is populated with any
+	// attachmentMetadata is populated with any
-	// information returned by the attach operation that must be passed
+	// information returned by the attach operation, upon successful attach, that must be passed
 	// into subsequent WaitForAttach or Mount calls.
 	// This field must only be set by the entity completing the attach
 	// operation, i.e. the external-attacher.
 	// +optional
 	AttachmentMetadata map[string]string `json:"attachmentMetadata,omitempty" protobuf:"bytes,2,rep,name=attachmentMetadata"`
 
-	// The last error encountered during attach operation, if any.
+	// attachError represents the last error encountered during attach operation, if any.
 	// This field must only be set by the entity completing the attach
 	// operation, i.e. the external-attacher.
 	// +optional
 	AttachError *VolumeError `json:"attachError,omitempty" protobuf:"bytes,3,opt,name=attachError,casttype=VolumeError"`
 
-	// The last error encountered during detach operation, if any.
+	// detachError represents the last error encountered during detach operation, if any.
 	// This field must only be set by the entity completing the detach
 	// operation, i.e. the external-attacher.
 	// +optional
@@ -220,11 +223,11 @@ type VolumeAttachmentStatus struct {
 
 // VolumeError captures an error encountered during a volume operation.
 type VolumeError struct {
-	// Time the error was encountered.
+	// time represents the time the error was encountered.
 	// +optional
 	Time metav1.Time `json:"time,omitempty" protobuf:"bytes,1,opt,name=time"`
 
-	// String detailing the error encountered during Attach or Detach operation.
+	// message represents the error encountered during Attach or Detach operation.
 	// This string may be logged, so it should not contain sensitive
 	// information.
 	// +optional
@@ -259,7 +262,7 @@ type CSIDriver struct {
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Specification of the CSI Driver.
+	// spec represents the specification of the CSI Driver.
 	Spec CSIDriverSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
 }
 
@@ -299,16 +302,15 @@ type CSIDriverSpec struct {
 	// +optional
 	AttachRequired *bool `json:"attachRequired,omitempty" protobuf:"varint,1,opt,name=attachRequired"`
 
-	// If set to true, podInfoOnMount indicates this CSI volume driver
+	// podInfoOnMount indicates this CSI volume driver requires additional pod information (like podName, podUID, etc.) 
-	// requires additional pod information (like podName, podUID, etc.) during
+	// during mount operations, if set to true.
-	// mount operations.
 	// If set to false, pod information will not be passed on mount.
 	// Default is false.
+	//
 	// The CSI driver specifies podInfoOnMount as part of driver deployment.
-	// If true, Kubelet will pass pod information as VolumeContext in the CSI
+	// If true, Kubelet will pass pod information as VolumeContext in the CSI NodePublishVolume() calls.
-	// NodePublishVolume() calls.
+	// The CSI driver is responsible for parsing and validating the information passed in as VolumeContext.
-	// The CSI driver is responsible for parsing and validating the information
+	//
-	// passed in as VolumeContext.
 	// The following VolumeConext will be passed if podInfoOnMount is set to true.
 	// This list might grow, but the prefix will be used.
 	// "csi.storage.k8s.io/pod.name": pod.Name
@@ -329,14 +331,14 @@ type CSIDriverSpec struct {
 	// +optional
 	PodInfoOnMount *bool `json:"podInfoOnMount,omitempty" protobuf:"bytes,2,opt,name=podInfoOnMount"`
 
-	// VolumeLifecycleModes defines what kind of volumes this CSI volume driver supports.
+	// volumeLifecycleModes defines what kind of volumes this CSI volume driver supports.
-	// The default if the list is empty is "Persistent", which is the usage
+	// The default if the list is empty is "Persistent", which is the usage defined by the 
-	// defined by the CSI specification and implemented in Kubernetes via the usual
+	// CSI specification and implemented in Kubernetes via the usual PV/PVC mechanism.
-	// PV/PVC mechanism.
+	//
-	// The other mode is "Ephemeral". In this mode, volumes are defined inline
+	// The other mode is "Ephemeral". In this mode, volumes are defined inline inside the pod spec 
-	// inside the pod spec with CSIVolumeSource and their lifecycle is tied to
+	// with CSIVolumeSource and their lifecycle is tied to the lifecycle of that pod.
-	// the lifecycle of that pod. A driver has to be aware of this
+	// A driver has to be aware of this because it is only going to get a NodePublishVolume call for such a volume.
-	// because it is only going to get a NodePublishVolume call for such a volume.
+	//
 	// For more information about implementing this mode, see
 	// https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html
 	// A driver can support one or more of these modes and
@@ -347,11 +349,9 @@ type CSIDriverSpec struct {
 	// +optional
 	VolumeLifecycleModes []VolumeLifecycleMode `json:"volumeLifecycleModes,omitempty" protobuf:"bytes,3,opt,name=volumeLifecycleModes"`
 
-	// If set to true, storageCapacity indicates that the CSI
+	// storageCapacity indicates that the CSI volume driver wants pod scheduling to consider the storage
-	// volume driver wants pod scheduling to consider the storage
 	// capacity that the driver deployment will report by creating
-	// CSIStorageCapacity objects with capacity information.
+	// CSIStorageCapacity objects with capacity information, if set to true.
-	//
 	//
 	// The check can be enabled immediately when deploying a driver.
 	// In that case, provisioning new volumes with late binding
@@ -367,7 +367,7 @@ type CSIDriverSpec struct {
 	// +optional
 	StorageCapacity *bool `json:"storageCapacity,omitempty" protobuf:"bytes,4,opt,name=storageCapacity"`
 
-	// Defines if the underlying volume supports changing ownership and
+	// fsGroupPolicy defines if the underlying volume supports changing ownership and
 	// permission of the volume before being mounted.
 	// Refer to the specific FSGroupPolicy values for additional details.
 	//
@@ -377,10 +377,11 @@ type CSIDriverSpec struct {
 	// to determine if Kubernetes should modify ownership and permissions of the volume.
 	// With the default policy the defined fsGroup will only be applied
 	// if a fstype is defined and the volume's access mode contains ReadWriteOnce.
+	//
 	// +optional
 	FSGroupPolicy *FSGroupPolicy `json:"fsGroupPolicy,omitempty" protobuf:"bytes,5,opt,name=fsGroupPolicy"`
 
-	// TokenRequests indicates the CSI driver needs pods' service account
+	// tokenRequests indicates the CSI driver needs pods' service account
 	// tokens it is mounting volume for to do necessary authentication. Kubelet
 	// will pass the tokens in VolumeContext in the CSI NodePublishVolume calls.
 	// The CSI driver should parse and validate the following VolumeContext:
@@ -400,7 +401,7 @@ type CSIDriverSpec struct {
 	// +listType=atomic
 	TokenRequests []TokenRequest `json:"tokenRequests,omitempty" protobuf:"bytes,6,opt,name=tokenRequests"`
 
-	// RequiresRepublish indicates the CSI driver wants `NodePublishVolume`
+	// requiresRepublish indicates the CSI driver wants `NodePublishVolume`
 	// being periodically called to reflect any possible change in the mounted
 	// volume. This field defaults to false.
 	//
@@ -411,7 +412,7 @@ type CSIDriverSpec struct {
 	// +optional
 	RequiresRepublish *bool `json:"requiresRepublish,omitempty" protobuf:"varint,7,opt,name=requiresRepublish"`
 
-	// SELinuxMount specifies if the CSI driver supports "-o context"
+	// seLinuxMount specifies if the CSI driver supports "-o context"
 	// mount option.
 	//
 	// When "true", the CSI driver must ensure that all volumes provided by this CSI
@@ -466,12 +467,11 @@ type VolumeLifecycleMode string
 
 // TokenRequest contains parameters of a service account token.
 type TokenRequest struct {
-	// Audience is the intended audience of the token in "TokenRequestSpec".
+	// audience is the intended audience of the token in "TokenRequestSpec".
 	// It will default to the audiences of kube apiserver.
-	//
 	Audience string `json:"audience" protobuf:"bytes,1,opt,name=audience"`
 
-	// ExpirationSeconds is the duration of validity of the token in "TokenRequestSpec".
+	// expirationSeconds is the duration of validity of the token in "TokenRequestSpec".
 	// It has the same default value of "ExpirationSeconds" in "TokenRequestSpec"
 	//
 	// +optional
@@ -539,7 +539,7 @@ type CSINodeSpec struct {
 
 // CSINodeDriver holds information about the specification of one CSI driver installed on a node
 type CSINodeDriver struct {
-	// This is the name of the CSI driver that this object refers to.
+	// name represents the name of the CSI driver that this object refers to.
 	// This MUST be the same name returned by the CSI GetPluginName() call for
 	// that driver.
 	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
@@ -575,7 +575,7 @@ type CSINodeDriver struct {
 
 // VolumeNodeResources is a set of resource limits for scheduling of volumes.
 type VolumeNodeResources struct {
-	// Maximum number of unique volumes managed by the CSI driver that can be used on a node.
+	// count indicates the maximum number of unique volumes managed by the CSI driver that can be used on a node.
 	// A volume that is both attached and mounted on a node is considered to be used once, not twice.
 	// The same rule applies for a unique volume that is shared among multiple pods on the same node.
 	// If this field is nil, then the supported number of volumes on this node is unbounded.
@@ -634,6 +634,7 @@ type CSINodeList struct {
 // node.
 type CSIStorageCapacity struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard object's metadata. The name has no particular meaning. It must be
 	// be a DNS subdomain (dots allowed, 253 characters). To ensure that
 	// there are no conflicts with other CSI drivers on the cluster, the recommendation
@@ -646,7 +647,7 @@ type CSIStorageCapacity struct {
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// NodeTopology defines which nodes have access to the storage
+	// nodeTopology defines which nodes have access to the storage
 	// for which capacity was reported. If not set, the storage is
 	// not accessible from any node in the cluster. If empty, the
 	// storage is accessible from all nodes. This field is
@@ -655,7 +656,7 @@ type CSIStorageCapacity struct {
 	// +optional
 	NodeTopology *metav1.LabelSelector `json:"nodeTopology,omitempty" protobuf:"bytes,2,opt,name=nodeTopology"`
 
-	// The name of the StorageClass that the reported capacity applies to.
+	// storageClassName represents the name of the StorageClass that the reported capacity applies to.
 	// It must meet the same requirements as the name of a StorageClass
 	// object (non-empty, DNS subdomain). If that object no longer exists,
 	// the CSIStorageCapacity object is obsolete and should be removed by its
@@ -663,7 +664,7 @@ type CSIStorageCapacity struct {
 	// This field is immutable.
 	StorageClassName string `json:"storageClassName" protobuf:"bytes,3,name=storageClassName"`
 
-	// Capacity is the value reported by the CSI driver in its GetCapacityResponse
+	// capacity is the value reported by the CSI driver in its GetCapacityResponse
 	// for a GetCapacityRequest with topology and parameters that match the
 	// previous fields.
 	//
@@ -675,7 +676,7 @@ type CSIStorageCapacity struct {
 	// +optional
 	Capacity *resource.Quantity `json:"capacity,omitempty" protobuf:"bytes,4,opt,name=capacity"`
 
-	// MaximumVolumeSize is the value reported by the CSI driver in its GetCapacityResponse
+	// maximumVolumeSize is the value reported by the CSI driver in its GetCapacityResponse
 	// for a GetCapacityRequest with topology and parameters that match the
 	// previous fields.
 	//
@@ -698,12 +699,13 @@ type CSIStorageCapacity struct {
 // CSIStorageCapacityList is a collection of CSIStorageCapacity objects.
 type CSIStorageCapacityList struct {
 	metav1.TypeMeta `json:",inline"`
+	
 	// Standard list metadata
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// Items is the list of CSIStorageCapacity objects.
+	// items is the list of CSIStorageCapacity objects.
 	// +listType=map
 	// +listMapKey=name
 	Items []CSIStorageCapacity `json:"items" protobuf:"bytes,2,rep,name=items"`