From 2aaf8b47b2bea38aa9f0c6082a087fd80960a272 Mon Sep 17 00:00:00 2001
From: Bowei Du <bowei@google.com>
Date: Fri, 5 Jan 2018 11:54:42 -0800
Subject: [PATCH] Clean up documentation.

---
 pkg/cloudprovider/providers/gce/cloud/doc.go  |  1 +
 .../providers/gce/cloud/gce_projects.go       |  6 +-
 pkg/cloudprovider/providers/gce/cloud/gen.go  | 95 +++++++++++++++++++
 .../providers/gce/cloud/gen/main.go           |  4 +-
 .../providers/gce/cloud/meta/method.go        | 11 ++-
 .../providers/gce/cloud/meta/service.go       |  4 +
 .../providers/gce/cloud/project.go            |  1 +
 .../providers/gce/cloud/ratelimit.go          |  1 +
 8 files changed, 120 insertions(+), 3 deletions(-)

diff --git a/pkg/cloudprovider/providers/gce/cloud/doc.go b/pkg/cloudprovider/providers/gce/cloud/doc.go
index d0d7a6cfb19..a6b121457cd 100644
--- a/pkg/cloudprovider/providers/gce/cloud/doc.go
+++ b/pkg/cloudprovider/providers/gce/cloud/doc.go
@@ -60,6 +60,7 @@ limitations under the License.
 //  &ServiceInfo{
 //    Object:      "InstanceGroup",   // Name of the object type.
 //    Service:     "InstanceGroups",  // Name of the service.
+//    Resource:    "instanceGroups",  // Lowercase resource name (as appears in the URL).
 //    version:     meta.VersionAlpha, // API version (one entry per version is needed).
 //    keyType:     Zonal,             // What kind of resource this is.
 //    serviceType: reflect.TypeOf(&alpha.InstanceGroupsService{}), // Associated golang type.
diff --git a/pkg/cloudprovider/providers/gce/cloud/gce_projects.go b/pkg/cloudprovider/providers/gce/cloud/gce_projects.go
index adc60927afc..c531881a94a 100644
--- a/pkg/cloudprovider/providers/gce/cloud/gce_projects.go
+++ b/pkg/cloudprovider/providers/gce/cloud/gce_projects.go
@@ -21,9 +21,9 @@ import (
 	"fmt"
 	"net/http"
 
-	"k8s.io/kubernetes/pkg/cloudprovider/providers/gce/cloud/meta"
 	compute "google.golang.org/api/compute/v1"
 	"google.golang.org/api/googleapi"
+	"k8s.io/kubernetes/pkg/cloudprovider/providers/gce/cloud/meta"
 )
 
 // ProjectsOps is the manually implemented methods for the Projects service.
@@ -37,6 +37,7 @@ type MockProjectOpsState struct {
 	metadata map[string]*compute.Metadata
 }
 
+// Get a project by projectID.
 func (m *MockProjects) Get(ctx context.Context, projectID string) (*compute.Project, error) {
 	m.Lock.Lock()
 	defer m.Lock.Unlock()
@@ -50,6 +51,7 @@ func (m *MockProjects) Get(ctx context.Context, projectID string) (*compute.Proj
 	}
 }
 
+// Get a project by projectID.
 func (g *GCEProjects) Get(ctx context.Context, projectID string) (*compute.Project, error) {
 	rk := &RateLimitKey{
 		ProjectID: projectID,
@@ -65,6 +67,7 @@ func (g *GCEProjects) Get(ctx context.Context, projectID string) (*compute.Proje
 	return call.Do()
 }
 
+// SetCommonInstanceMetadata for a given project.
 func (m *MockProjects) SetCommonInstanceMetadata(ctx context.Context, projectID string, meta *compute.Metadata) error {
 	if m.X == nil {
 		m.X = &MockProjectOpsState{metadata: map[string]*compute.Metadata{}}
@@ -74,6 +77,7 @@ func (m *MockProjects) SetCommonInstanceMetadata(ctx context.Context, projectID
 	return nil
 }
 
+// SetCommonInstanceMetadata for a given project.
 func (g *GCEProjects) SetCommonInstanceMetadata(ctx context.Context, projectID string, m *compute.Metadata) error {
 	rk := &RateLimitKey{
 		ProjectID: projectID,
diff --git a/pkg/cloudprovider/providers/gce/cloud/gen.go b/pkg/cloudprovider/providers/gce/cloud/gen.go
index ef7a2c62eaf..33a2b7ba619 100644
--- a/pkg/cloudprovider/providers/gce/cloud/gen.go
+++ b/pkg/cloudprovider/providers/gce/cloud/gen.go
@@ -150,99 +150,162 @@ type GCE struct {
 	gceZones                      *GCEZones
 }
 
+// Addresses returns the interface for the ga Addresses.
 func (gce *GCE) Addresses() Addresses {
 	return gce.gceAddresses
 }
+
+// AlphaAddresses returns the interface for the alpha Addresses.
 func (gce *GCE) AlphaAddresses() AlphaAddresses {
 	return gce.gceAlphaAddresses
 }
+
+// BetaAddresses returns the interface for the beta Addresses.
 func (gce *GCE) BetaAddresses() BetaAddresses {
 	return gce.gceBetaAddresses
 }
+
+// GlobalAddresses returns the interface for the ga GlobalAddresses.
 func (gce *GCE) GlobalAddresses() GlobalAddresses {
 	return gce.gceGlobalAddresses
 }
+
+// BackendServices returns the interface for the ga BackendServices.
 func (gce *GCE) BackendServices() BackendServices {
 	return gce.gceBackendServices
 }
+
+// AlphaBackendServices returns the interface for the alpha BackendServices.
 func (gce *GCE) AlphaBackendServices() AlphaBackendServices {
 	return gce.gceAlphaBackendServices
 }
+
+// AlphaRegionBackendServices returns the interface for the alpha RegionBackendServices.
 func (gce *GCE) AlphaRegionBackendServices() AlphaRegionBackendServices {
 	return gce.gceAlphaRegionBackendServices
 }
+
+// Disks returns the interface for the ga Disks.
 func (gce *GCE) Disks() Disks {
 	return gce.gceDisks
 }
+
+// AlphaDisks returns the interface for the alpha Disks.
 func (gce *GCE) AlphaDisks() AlphaDisks {
 	return gce.gceAlphaDisks
 }
+
+// AlphaRegionDisks returns the interface for the alpha RegionDisks.
 func (gce *GCE) AlphaRegionDisks() AlphaRegionDisks {
 	return gce.gceAlphaRegionDisks
 }
+
+// Firewalls returns the interface for the ga Firewalls.
 func (gce *GCE) Firewalls() Firewalls {
 	return gce.gceFirewalls
 }
+
+// ForwardingRules returns the interface for the ga ForwardingRules.
 func (gce *GCE) ForwardingRules() ForwardingRules {
 	return gce.gceForwardingRules
 }
+
+// AlphaForwardingRules returns the interface for the alpha ForwardingRules.
 func (gce *GCE) AlphaForwardingRules() AlphaForwardingRules {
 	return gce.gceAlphaForwardingRules
 }
+
+// GlobalForwardingRules returns the interface for the ga GlobalForwardingRules.
 func (gce *GCE) GlobalForwardingRules() GlobalForwardingRules {
 	return gce.gceGlobalForwardingRules
 }
+
+// HealthChecks returns the interface for the ga HealthChecks.
 func (gce *GCE) HealthChecks() HealthChecks {
 	return gce.gceHealthChecks
 }
+
+// AlphaHealthChecks returns the interface for the alpha HealthChecks.
 func (gce *GCE) AlphaHealthChecks() AlphaHealthChecks {
 	return gce.gceAlphaHealthChecks
 }
+
+// HttpHealthChecks returns the interface for the ga HttpHealthChecks.
 func (gce *GCE) HttpHealthChecks() HttpHealthChecks {
 	return gce.gceHttpHealthChecks
 }
+
+// HttpsHealthChecks returns the interface for the ga HttpsHealthChecks.
 func (gce *GCE) HttpsHealthChecks() HttpsHealthChecks {
 	return gce.gceHttpsHealthChecks
 }
+
+// InstanceGroups returns the interface for the ga InstanceGroups.
 func (gce *GCE) InstanceGroups() InstanceGroups {
 	return gce.gceInstanceGroups
 }
+
+// Instances returns the interface for the ga Instances.
 func (gce *GCE) Instances() Instances {
 	return gce.gceInstances
 }
+
+// BetaInstances returns the interface for the beta Instances.
 func (gce *GCE) BetaInstances() BetaInstances {
 	return gce.gceBetaInstances
 }
+
+// AlphaInstances returns the interface for the alpha Instances.
 func (gce *GCE) AlphaInstances() AlphaInstances {
 	return gce.gceAlphaInstances
 }
+
+// AlphaNetworkEndpointGroups returns the interface for the alpha NetworkEndpointGroups.
 func (gce *GCE) AlphaNetworkEndpointGroups() AlphaNetworkEndpointGroups {
 	return gce.gceAlphaNetworkEndpointGroups
 }
+
+// Projects returns the interface for the ga Projects.
 func (gce *GCE) Projects() Projects {
 	return gce.gceProjects
 }
+
+// Regions returns the interface for the ga Regions.
 func (gce *GCE) Regions() Regions {
 	return gce.gceRegions
 }
+
+// Routes returns the interface for the ga Routes.
 func (gce *GCE) Routes() Routes {
 	return gce.gceRoutes
 }
+
+// SslCertificates returns the interface for the ga SslCertificates.
 func (gce *GCE) SslCertificates() SslCertificates {
 	return gce.gceSslCertificates
 }
+
+// TargetHttpProxies returns the interface for the ga TargetHttpProxies.
 func (gce *GCE) TargetHttpProxies() TargetHttpProxies {
 	return gce.gceTargetHttpProxies
 }
+
+// TargetHttpsProxies returns the interface for the ga TargetHttpsProxies.
 func (gce *GCE) TargetHttpsProxies() TargetHttpsProxies {
 	return gce.gceTargetHttpsProxies
 }
+
+// TargetPools returns the interface for the ga TargetPools.
 func (gce *GCE) TargetPools() TargetPools {
 	return gce.gceTargetPools
 }
+
+// UrlMaps returns the interface for the ga UrlMaps.
 func (gce *GCE) UrlMaps() UrlMaps {
 	return gce.gceUrlMaps
 }
+
+// Zones returns the interface for the ga Zones.
 func (gce *GCE) Zones() Zones {
 	return gce.gceZones
 }
@@ -350,130 +413,162 @@ type MockGCE struct {
 	MockZones                      *MockZones
 }
 
+// Addresses returns the interface for the ga Addresses.
 func (mock *MockGCE) Addresses() Addresses {
 	return mock.MockAddresses
 }
 
+// AlphaAddresses returns the interface for the alpha Addresses.
 func (mock *MockGCE) AlphaAddresses() AlphaAddresses {
 	return mock.MockAlphaAddresses
 }
 
+// BetaAddresses returns the interface for the beta Addresses.
 func (mock *MockGCE) BetaAddresses() BetaAddresses {
 	return mock.MockBetaAddresses
 }
 
+// GlobalAddresses returns the interface for the ga GlobalAddresses.
 func (mock *MockGCE) GlobalAddresses() GlobalAddresses {
 	return mock.MockGlobalAddresses
 }
 
+// BackendServices returns the interface for the ga BackendServices.
 func (mock *MockGCE) BackendServices() BackendServices {
 	return mock.MockBackendServices
 }
 
+// AlphaBackendServices returns the interface for the alpha BackendServices.
 func (mock *MockGCE) AlphaBackendServices() AlphaBackendServices {
 	return mock.MockAlphaBackendServices
 }
 
+// AlphaRegionBackendServices returns the interface for the alpha RegionBackendServices.
 func (mock *MockGCE) AlphaRegionBackendServices() AlphaRegionBackendServices {
 	return mock.MockAlphaRegionBackendServices
 }
 
+// Disks returns the interface for the ga Disks.
 func (mock *MockGCE) Disks() Disks {
 	return mock.MockDisks
 }
 
+// AlphaDisks returns the interface for the alpha Disks.
 func (mock *MockGCE) AlphaDisks() AlphaDisks {
 	return mock.MockAlphaDisks
 }
 
+// AlphaRegionDisks returns the interface for the alpha RegionDisks.
 func (mock *MockGCE) AlphaRegionDisks() AlphaRegionDisks {
 	return mock.MockAlphaRegionDisks
 }
 
+// Firewalls returns the interface for the ga Firewalls.
 func (mock *MockGCE) Firewalls() Firewalls {
 	return mock.MockFirewalls
 }
 
+// ForwardingRules returns the interface for the ga ForwardingRules.
 func (mock *MockGCE) ForwardingRules() ForwardingRules {
 	return mock.MockForwardingRules
 }
 
+// AlphaForwardingRules returns the interface for the alpha ForwardingRules.
 func (mock *MockGCE) AlphaForwardingRules() AlphaForwardingRules {
 	return mock.MockAlphaForwardingRules
 }
 
+// GlobalForwardingRules returns the interface for the ga GlobalForwardingRules.
 func (mock *MockGCE) GlobalForwardingRules() GlobalForwardingRules {
 	return mock.MockGlobalForwardingRules
 }
 
+// HealthChecks returns the interface for the ga HealthChecks.
 func (mock *MockGCE) HealthChecks() HealthChecks {
 	return mock.MockHealthChecks
 }
 
+// AlphaHealthChecks returns the interface for the alpha HealthChecks.
 func (mock *MockGCE) AlphaHealthChecks() AlphaHealthChecks {
 	return mock.MockAlphaHealthChecks
 }
 
+// HttpHealthChecks returns the interface for the ga HttpHealthChecks.
 func (mock *MockGCE) HttpHealthChecks() HttpHealthChecks {
 	return mock.MockHttpHealthChecks
 }
 
+// HttpsHealthChecks returns the interface for the ga HttpsHealthChecks.
 func (mock *MockGCE) HttpsHealthChecks() HttpsHealthChecks {
 	return mock.MockHttpsHealthChecks
 }
 
+// InstanceGroups returns the interface for the ga InstanceGroups.
 func (mock *MockGCE) InstanceGroups() InstanceGroups {
 	return mock.MockInstanceGroups
 }
 
+// Instances returns the interface for the ga Instances.
 func (mock *MockGCE) Instances() Instances {
 	return mock.MockInstances
 }
 
+// BetaInstances returns the interface for the beta Instances.
 func (mock *MockGCE) BetaInstances() BetaInstances {
 	return mock.MockBetaInstances
 }
 
+// AlphaInstances returns the interface for the alpha Instances.
 func (mock *MockGCE) AlphaInstances() AlphaInstances {
 	return mock.MockAlphaInstances
 }
 
+// AlphaNetworkEndpointGroups returns the interface for the alpha NetworkEndpointGroups.
 func (mock *MockGCE) AlphaNetworkEndpointGroups() AlphaNetworkEndpointGroups {
 	return mock.MockAlphaNetworkEndpointGroups
 }
 
+// Projects returns the interface for the ga Projects.
 func (mock *MockGCE) Projects() Projects {
 	return mock.MockProjects
 }
 
+// Regions returns the interface for the ga Regions.
 func (mock *MockGCE) Regions() Regions {
 	return mock.MockRegions
 }
 
+// Routes returns the interface for the ga Routes.
 func (mock *MockGCE) Routes() Routes {
 	return mock.MockRoutes
 }
 
+// SslCertificates returns the interface for the ga SslCertificates.
 func (mock *MockGCE) SslCertificates() SslCertificates {
 	return mock.MockSslCertificates
 }
 
+// TargetHttpProxies returns the interface for the ga TargetHttpProxies.
 func (mock *MockGCE) TargetHttpProxies() TargetHttpProxies {
 	return mock.MockTargetHttpProxies
 }
 
+// TargetHttpsProxies returns the interface for the ga TargetHttpsProxies.
 func (mock *MockGCE) TargetHttpsProxies() TargetHttpsProxies {
 	return mock.MockTargetHttpsProxies
 }
 
+// TargetPools returns the interface for the ga TargetPools.
 func (mock *MockGCE) TargetPools() TargetPools {
 	return mock.MockTargetPools
 }
 
+// UrlMaps returns the interface for the ga UrlMaps.
 func (mock *MockGCE) UrlMaps() UrlMaps {
 	return mock.MockUrlMaps
 }
 
+// Zones returns the interface for the ga Zones.
 func (mock *MockGCE) Zones() Zones {
 	return mock.MockZones
 }
diff --git a/pkg/cloudprovider/providers/gce/cloud/gen/main.go b/pkg/cloudprovider/providers/gce/cloud/gen/main.go
index f8dcd730b9f..7217d35c5d6 100644
--- a/pkg/cloudprovider/providers/gce/cloud/gen/main.go
+++ b/pkg/cloudprovider/providers/gce/cloud/gen/main.go
@@ -30,8 +30,8 @@ import (
 	"text/template"
 	"time"
 
-	"k8s.io/kubernetes/pkg/cloudprovider/providers/gce/cloud/meta"
 	"github.com/golang/glog"
+	"k8s.io/kubernetes/pkg/cloudprovider/providers/gce/cloud/meta"
 )
 
 const (
@@ -167,6 +167,7 @@ type GCE struct {
 }
 
 {{range .All}}
+// {{.WrapType}} returns the interface for the {{.Version}} {{.Service}}.
 func (gce *GCE) {{.WrapType}}() {{.WrapType}} {
 	return gce.{{.Field}}
 }
@@ -196,6 +197,7 @@ type MockGCE struct {
 {{- end}}
 }
 {{range .All}}
+// {{.WrapType}} returns the interface for the {{.Version}} {{.Service}}.
 func (mock *MockGCE) {{.WrapType}}() {{.WrapType}} {
 	return mock.{{.MockField}}
 }
diff --git a/pkg/cloudprovider/providers/gce/cloud/meta/method.go b/pkg/cloudprovider/providers/gce/cloud/meta/method.go
index 5adf065fae4..c3a33d801d3 100644
--- a/pkg/cloudprovider/providers/gce/cloud/meta/method.go
+++ b/pkg/cloudprovider/providers/gce/cloud/meta/method.go
@@ -91,7 +91,7 @@ func newMethod(s *ServiceInfo, m reflect.Method) *Method {
 	return ret
 }
 
-// Method is used to generate the calling code non-standard methods.
+// Method is used to generate the calling code for non-standard methods.
 type Method struct {
 	*ServiceInfo
 	m reflect.Method
@@ -135,6 +135,7 @@ func (mr *Method) args(skip int, nameArgs bool, prefix []string) []string {
 	return append(prefix, a...)
 }
 
+// init the method, preforming some rudimentary static checking.
 func (mr *Method) init() {
 	fType := mr.m.Func.Type()
 	if fType.NumIn() < mr.argsSkip() {
@@ -189,10 +190,14 @@ func (mr *Method) init() {
 	}
 }
 
+// Name is the name of the method.
 func (mr *Method) Name() string {
 	return mr.m.Name
 }
 
+// CallArgs is a list of comma separated "argN" used for calling the method.
+// For example, if the method has two additional arguments, this will return
+// "arg0, arg1".
 func (mr *Method) CallArgs() string {
 	var args []string
 	for i := mr.argsSkip(); i < mr.m.Func.Type().NumIn(); i++ {
@@ -204,10 +209,12 @@ func (mr *Method) CallArgs() string {
 	return fmt.Sprintf(", %s", strings.Join(args, ", "))
 }
 
+// MockHookName is the name of the hook function in the mock.
 func (mr *Method) MockHookName() string {
 	return mr.m.Name + "Hook"
 }
 
+// MockHook is the definition of the hook function.
 func (mr *Method) MockHook() string {
 	args := mr.args(mr.argsSkip(), false, []string{
 		fmt.Sprintf("*%s", mr.MockWrapType()),
@@ -220,6 +227,7 @@ func (mr *Method) MockHook() string {
 	return fmt.Sprintf("%v func(%v) (*%v.%v, error)", mr.MockHookName(), strings.Join(args, ", "), mr.Version(), mr.ReturnType)
 }
 
+// FcnArgs is the function signature for the definition of the method.
 func (mr *Method) FcnArgs() string {
 	args := mr.args(mr.argsSkip(), true, []string{
 		"ctx context.Context",
@@ -232,6 +240,7 @@ func (mr *Method) FcnArgs() string {
 	return fmt.Sprintf("%v(%v) (*%v.%v, error)", mr.m.Name, strings.Join(args, ", "), mr.Version(), mr.ReturnType)
 }
 
+// InterfaceFunc is the function declaration of the method in the interface.
 func (mr *Method) InterfaceFunc() string {
 	args := mr.args(mr.argsSkip(), false, []string{"context.Context", "meta.Key"})
 	if mr.ReturnType == "Operation" {
diff --git a/pkg/cloudprovider/providers/gce/cloud/meta/service.go b/pkg/cloudprovider/providers/gce/cloud/meta/service.go
index ffa3385075b..b2ba91c8ec5 100644
--- a/pkg/cloudprovider/providers/gce/cloud/meta/service.go
+++ b/pkg/cloudprovider/providers/gce/cloud/meta/service.go
@@ -220,6 +220,7 @@ type ServiceGroup struct {
 	GA    *ServiceInfo
 }
 
+// Service returns any ServiceInfo object belonging to the ServiceGroup.
 func (sg *ServiceGroup) Service() string {
 	switch {
 	case sg.GA != nil:
@@ -233,14 +234,17 @@ func (sg *ServiceGroup) Service() string {
 	}
 }
 
+// HasGA returns true if this object has a GA representation.
 func (sg *ServiceGroup) HasGA() bool {
 	return sg.GA != nil
 }
 
+// HasAlpha returns true if this object has a Alpha representation.
 func (sg *ServiceGroup) HasAlpha() bool {
 	return sg.Alpha != nil
 }
 
+// HasBeta returns true if this object has a Beta representation.
 func (sg *ServiceGroup) HasBeta() bool {
 	return sg.Beta != nil
 }
diff --git a/pkg/cloudprovider/providers/gce/cloud/project.go b/pkg/cloudprovider/providers/gce/cloud/project.go
index 74299e4a23e..231e7cf916a 100644
--- a/pkg/cloudprovider/providers/gce/cloud/project.go
+++ b/pkg/cloudprovider/providers/gce/cloud/project.go
@@ -39,6 +39,7 @@ type SingleProjectRouter struct {
 	ID string
 }
 
+// ProjectID returns the project ID to be used for a call to the API.
 func (r *SingleProjectRouter) ProjectID(ctx context.Context, version meta.Version, service string) string {
 	return r.ID
 }
diff --git a/pkg/cloudprovider/providers/gce/cloud/ratelimit.go b/pkg/cloudprovider/providers/gce/cloud/ratelimit.go
index 948f1d36d89..e38b8f7de3c 100644
--- a/pkg/cloudprovider/providers/gce/cloud/ratelimit.go
+++ b/pkg/cloudprovider/providers/gce/cloud/ratelimit.go
@@ -51,6 +51,7 @@ type RateLimiter interface {
 type NopRateLimiter struct {
 }
 
+// Accept the operation to be rate limited.
 func (*NopRateLimiter) Accept(ctx context.Context, key *RateLimitKey) error {
 	// Rate limit polling of the Operation status to avoid hammering GCE
 	// for the status of an operation.