Tidy godoc comments

Signed-off-by: Jake Sanders <i@am.so-aweso.me>

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)

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

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,

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)

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"
 )
 

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:

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 {

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)
 }