From 196e42c2211f66d10d03e0a8315f956abc35b4f7 Mon Sep 17 00:00:00 2001 From: Jake Sanders Date: Wed, 5 May 2021 16:21:24 +0100 Subject: [PATCH] Tidy godoc comments Signed-off-by: Jake Sanders --- pkg/acme/client/interfaces.go | 4 +++- pkg/acme/webhook/apis/acme/v1alpha1/register.go | 2 +- pkg/controller/certificaterequests/acme/acme.go | 6 +++--- pkg/controller/certificaterequests/util/reporter.go | 12 +++++++----- pkg/controller/certificates/metrics/controller.go | 2 +- pkg/controller/helper.go | 2 +- pkg/controller/test/util.go | 2 +- pkg/internal/vault/fake/vault.go | 10 +++++----- 8 files changed, 22 insertions(+), 18 deletions(-) diff --git a/pkg/acme/client/interfaces.go b/pkg/acme/client/interfaces.go index 0382e9ed1..e920d46ea 100644 --- a/pkg/acme/client/interfaces.go +++ b/pkg/acme/client/interfaces.go @@ -26,7 +26,9 @@ import ( // Interface is an Automatic Certificate Management Environment (ACME) client // implementing an Order-based flow. -// For more information see RFC 8555 (https://tools.ietf.org/html/rfc8555). +// +// For more information see https://pkg.go.dev/golang.org/x/crypto/acme#Client +// and RFC 8555 (https://tools.ietf.org/html/rfc8555). type Interface interface { AuthorizeOrder(ctx context.Context, id []acme.AuthzID, opt ...acme.OrderOption) (*acme.Order, error) GetOrder(ctx context.Context, url string) (*acme.Order, error) diff --git a/pkg/acme/webhook/apis/acme/v1alpha1/register.go b/pkg/acme/webhook/apis/acme/v1alpha1/register.go index 8617c6a3a..417a70597 100644 --- a/pkg/acme/webhook/apis/acme/v1alpha1/register.go +++ b/pkg/acme/webhook/apis/acme/v1alpha1/register.go @@ -34,7 +34,7 @@ func Resource(resource string) schema.GroupResource { var ( // SchemeBuilder should be declared in packages that will have generated deep - // copy or conversion functions + // copy or conversion functions. SchemeBuilder runtime.SchemeBuilder localSchemeBuilder = &SchemeBuilder AddToScheme = localSchemeBuilder.AddToScheme diff --git a/pkg/controller/certificaterequests/acme/acme.go b/pkg/controller/certificaterequests/acme/acme.go index 3f62f8483..80194baed 100644 --- a/pkg/controller/certificaterequests/acme/acme.go +++ b/pkg/controller/certificaterequests/acme/acme.go @@ -43,11 +43,11 @@ import ( const ( // CRControllerName is the string used to refer to // this controller when enabling or disabling it from - // command line flags + // command line flags. CRControllerName = "certificaterequests-issuer-acme" ) -// ACME is a controller that implements `certificaterequests.Issuer` +// ACME is a controller that implements `certificaterequests.Issuer`. type ACME struct { // used to record Events about resources to the API recorder record.EventRecorder @@ -71,7 +71,7 @@ func init() { }) } -// NewACME returns a configured controller +// NewACME returns a configured controller. func NewACME(ctx *controllerpkg.Context) *ACME { return &ACME{ recorder: ctx.Recorder, diff --git a/pkg/controller/certificaterequests/util/reporter.go b/pkg/controller/certificaterequests/util/reporter.go index 20f13949d..9ebbba974 100644 --- a/pkg/controller/certificaterequests/util/reporter.go +++ b/pkg/controller/certificaterequests/util/reporter.go @@ -34,13 +34,13 @@ const ( ) // A Reporter updates the Status of a CertificateRequest and sends an event -// to the Kubernetes Events API +// to the Kubernetes Events API. type Reporter struct { clock clock.Clock recorder record.EventRecorder } -// NewReporter returns a Reporter that will send events to the given EventRecorder +// NewReporter returns a Reporter that will send events to the given EventRecorder. func NewReporter(clock clock.Clock, recorder record.EventRecorder) *Reporter { return &Reporter{ clock: clock, @@ -63,7 +63,8 @@ func (r *Reporter) Failed(cr *cmapi.CertificateRequest, err error, reason, messa } -// Denied marks a CertificateRequest as terminally denied +// Denied marks a CertificateRequest as terminally denied. No event is sent as it is +// expected to be sent by the approval controller. func (r *Reporter) Denied(cr *cmapi.CertificateRequest) { // Set the FailureTime to c.clock.Now(), only if it has not been already set. if cr.Status.FailureTime == nil { @@ -76,7 +77,8 @@ func (r *Reporter) Denied(cr *cmapi.CertificateRequest) { cmmeta.ConditionFalse, cmapi.CertificateRequestReasonDenied, message) } -// InvalidRequest marks a CertificateRequest as terminally Invalid +// InvalidRequest marks a CertificateRequest as terminally Invalid. No event is sent as it +// is expected to be reported by the order controller. func (r *Reporter) InvalidRequest(cr *cmapi.CertificateRequest, reason, message string) { apiutil.SetCertificateRequestCondition(cr, cmapi.CertificateRequestConditionInvalidRequest, cmmeta.ConditionTrue, reason, message) @@ -84,7 +86,7 @@ func (r *Reporter) InvalidRequest(cr *cmapi.CertificateRequest, reason, message // Pending marks a CertificateRequest as pending and sends a corresponding event. // -// The event is only sent if the CertificateRequest is not already pending +// The event is only sent if the CertificateRequest is not already pending. func (r *Reporter) Pending(cr *cmapi.CertificateRequest, err error, reason, message string) { if err != nil { message = fmt.Sprintf("%s: %v", message, err) diff --git a/pkg/controller/certificates/metrics/controller.go b/pkg/controller/certificates/metrics/controller.go index 44cb65da4..039d25636 100644 --- a/pkg/controller/certificates/metrics/controller.go +++ b/pkg/controller/certificates/metrics/controller.go @@ -33,7 +33,7 @@ import ( const ( // ControllerName is the string used to refer to this controller - // when enabling or disabling it from command line flags + // when enabling or disabling it from command line flags. ControllerName = "certificates-metrics" ) diff --git a/pkg/controller/helper.go b/pkg/controller/helper.go index d21fb38e0..0643e1855 100644 --- a/pkg/controller/helper.go +++ b/pkg/controller/helper.go @@ -31,7 +31,7 @@ func (o IssuerOptions) ResourceNamespace(iss cmapi.GenericIssuer) string { } // CanUseAmbientCredentials returns whether `iss` will attempt to configure itself -// from ambient credentials (e.g. from a cloud metadata service) +// from ambient credentials (e.g. from a cloud metadata service). func (o IssuerOptions) CanUseAmbientCredentials(iss cmapi.GenericIssuer) bool { switch iss.(type) { case *cmapi.ClusterIssuer: diff --git a/pkg/controller/test/util.go b/pkg/controller/test/util.go index 15b767f0f..51bbc598e 100644 --- a/pkg/controller/test/util.go +++ b/pkg/controller/test/util.go @@ -29,7 +29,7 @@ type StringGenerator func(n int) string const letterBytes = "abcdefghijklmnopqrstuvwxyz0123456789" -// RandStringBytes generates a pseudo-random string of length n +// RandStringBytes generates a pseudo-random string of length `n`. func RandStringBytes(n int) string { b := make([]byte, n) for i := range b { diff --git a/pkg/internal/vault/fake/vault.go b/pkg/internal/vault/fake/vault.go index 2561817d2..c87bbcfab 100644 --- a/pkg/internal/vault/fake/vault.go +++ b/pkg/internal/vault/fake/vault.go @@ -50,12 +50,12 @@ func New() *Vault { return v } -// Sign implements vault.Interface +// Sign implements `vault.Interface`. func (v *Vault) Sign(csrPEM []byte, duration time.Duration) ([]byte, []byte, error) { return v.SignFn(csrPEM, duration) } -// WithSign sets the fake Vault's Sign function +// WithSign sets the fake Vault's Sign function. func (v *Vault) WithSign(certPEM, caPEM []byte, err error) *Vault { v.SignFn = func([]byte, time.Duration) ([]byte, []byte, error) { return certPEM, caPEM, err @@ -63,13 +63,13 @@ func (v *Vault) WithSign(certPEM, caPEM []byte, err error) *Vault { return v } -// WithNew sets the fake Vault's New function +// WithNew sets the fake Vault's New function. func (v *Vault) WithNew(f func(string, corelisters.SecretLister, v1.GenericIssuer) (*Vault, error)) *Vault { v.NewFn = f return v } -// New call NewFn and returns a pointer to the fake Vault +// New call NewFn and returns a pointer to the fake Vault. func (v *Vault) New(ns string, sl corelisters.SecretLister, iss v1.GenericIssuer) (*Vault, error) { _, err := v.NewFn(ns, sl, iss) if err != nil { @@ -79,7 +79,7 @@ func (v *Vault) New(ns string, sl corelisters.SecretLister, iss v1.GenericIssuer return v, nil } -// Sys returns an empty vault.Sys +// Sys returns an empty `vault.Sys`. func (v *Vault) Sys() *vault.Sys { return new(vault.Sys) }