Deployment: Update Lister documentation for ControllerRef.

The Deployment Listers still use selectors, because this is the
behavior expected by callers. This clarifies the meaning of the
returned list. Some callers may need to switch to using
GetControllerOf() instead, but that is a separate, case-by-case issue.

pkg/client/listers/extensions/internalversion/deployment_expansion.go

@@ -34,7 +34,10 @@ type DeploymentListerExpansion interface {
 // DeploymentNamespaeLister.
 type DeploymentNamespaceListerExpansion interface{}
 
-// GetDeploymentsForReplicaSet returns a list of deployments managing a replica set. Returns an error only if no matching deployments are found.
+// GetDeploymentsForReplicaSet returns a list of Deployments that potentially
+// match a ReplicaSet. Only the one specified in the ReplicaSet's ControllerRef
+// will actually manage it.
+// Returns an error only if no matching Deployments are found.
 func (s *deploymentLister) GetDeploymentsForReplicaSet(rs *extensions.ReplicaSet) ([]*extensions.Deployment, error) {
 	if len(rs.Labels) == 0 {
 		return nil, fmt.Errorf("no deployments found for ReplicaSet %v because it has no labels", rs.Name)

pkg/client/listers/extensions/v1beta1/deployment_expansion.go

@@ -34,7 +34,10 @@ type DeploymentListerExpansion interface {
 // DeploymentNamespaeLister.
 type DeploymentNamespaceListerExpansion interface{}
 
-// GetDeploymentsForReplicaSet returns a list of deployments managing a replica set. Returns an error only if no matching deployments are found.
+// GetDeploymentsForReplicaSet returns a list of Deployments that potentially
+// match a ReplicaSet. Only the one specified in the ReplicaSet's ControllerRef
+// will actually manage it.
+// Returns an error only if no matching Deployments are found.
 func (s *deploymentLister) GetDeploymentsForReplicaSet(rs *extensions.ReplicaSet) ([]*extensions.Deployment, error) {
 	if len(rs.Labels) == 0 {
 		return nil, fmt.Errorf("no deployments found for ReplicaSet %v because it has no labels", rs.Name)

staging/src/k8s.io/client-go/listers/extensions/v1beta1/deployment_expansion.go

@@ -34,7 +34,10 @@ type DeploymentListerExpansion interface {
 // DeploymentNamespaeLister.
 type DeploymentNamespaceListerExpansion interface{}
 
-// GetDeploymentsForReplicaSet returns a list of deployments managing a replica set. Returns an error only if no matching deployments are found.
+// GetDeploymentsForReplicaSet returns a list of Deployments that potentially
+// match a ReplicaSet. Only the one specified in the ReplicaSet's ControllerRef
+// will actually manage it.
+// Returns an error only if no matching Deployments are found.
 func (s *deploymentLister) GetDeploymentsForReplicaSet(rs *extensions.ReplicaSet) ([]*extensions.Deployment, error) {
 	if len(rs.Labels) == 0 {
 		return nil, fmt.Errorf("no deployments found for ReplicaSet %v because it has no labels", rs.Name)