Merge pull request #790 from sapcc/missing_docs_findings

fix missing documentation lints

Author: majewsky

internal/api/api_test.go

@@ -309,14 +309,14 @@ func Test_ScrapeErrorOperations(t *testing.T) {
 		ExpectBody:   assert.JSONObject{"scrape_errors": []assert.JSONObject{}},
 	}.Check(t, s.Handler)
 
-	// Add a scrape error to one specific service with type 'unshared'.
+	// add a scrape error to one specific service with type 'unshared'.
 	s.MustDBExec(
 		`UPDATE project_services SET scrape_error_message = $1 WHERE project_id = 1 AND service_id = $2`,
 		"could not scrape this specific unshared service",
 		s.GetServiceID("unshared"),
 	)
 
-	// Add the same scrape error to all services with type 'shared'. This will ensure that
+	// add the same scrape error to all services with type 'shared'. This will ensure that
 	// they get grouped under a dummy project.
 	s.MustDBExec(
 		`UPDATE project_services SET scrape_error_message = $1 WHERE service_id = $2`,

internal/api/commitment.go

@@ -1733,7 +1733,7 @@ func (p *v1Provider) TransferCommitment(w http.ResponseWriter, r *http.Request)
 	respondwith.JSON(w, http.StatusAccepted, map[string]any{"commitment": c})
 }
 
-// GetCommitmentConversion handles GET /v1/commitment-conversion/{service_type}/{resource_name}
+// GetCommitmentConversions handles GET /v1/commitment-conversion/{service_type}/{resource_name}
 func (p *v1Provider) GetCommitmentConversions(w http.ResponseWriter, r *http.Request) {
 	httpapi.IdentifyEndpoint(r, "/v1/commitment-conversion/:service_type/:resource_name")
 	token := p.CheckToken(r)
@@ -2113,7 +2113,7 @@ func (p *v1Provider) ConvertCommitment(w http.ResponseWriter, r *http.Request) {
 	respondwith.JSON(w, http.StatusAccepted, map[string]any{"commitment": c})
 }
 
-// ExtendCommitmentDuration handles POST /v1/domains/{domain_id}/projects/{project_id}/commitments/{commitment_id}/update-duration
+// UpdateCommitmentDuration handles POST /v1/domains/{domain_id}/projects/{project_id}/commitments/{commitment_id}/update-duration
 func (p *v1Provider) UpdateCommitmentDuration(w http.ResponseWriter, r *http.Request) {
 	httpapi.IdentifyEndpoint(r, "/v1/domains/:domain_id/projects/:project_id/commitments/:commitment_id/update-duration")
 	token := p.CheckToken(r)

internal/api/core.go

@@ -101,11 +101,6 @@ func NewTokenValidator(provider *gophercloud.ProviderClient, eo gophercloud.Endp
 	return &tv, err
 }
 
-func (p *v1Provider) OverrideGenerateTransferToken(generateTransferToken func() string) *v1Provider {
-	p.generateTransferToken = generateTransferToken
-	return p
-}
-
 // AddTo implements the httpapi.API interface.
 func (p *v1Provider) AddTo(r *mux.Router) {
 	r.Methods("HEAD", "GET").Path("/").HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

internal/api/liquid.go

@@ -52,7 +52,7 @@ func (p *v1Provider) GetServiceCapacityRequest(w http.ResponseWriter, r *http.Re
 	respondwith.JSON(w, http.StatusOK, serviceCapacityRequest)
 }
 
-// p.GetServiceUsageRequest handles GET /admin/liquid/service-usage-request?service_type=:type&project_id=:id.
+// GetServiceUsageRequest handles GET /admin/liquid/service-usage-request?service_type=:type&project_id=:id.
 func (p *v1Provider) GetServiceUsageRequest(w http.ResponseWriter, r *http.Request) {
 	httpapi.IdentifyEndpoint(r, "/admin/liquid/service-usage-request")
 	token := p.CheckToken(r)

internal/api/stream.go

@@ -37,6 +37,7 @@ type JSONListStream[T any] struct {
 	w *bufio.Writer
 }
 
+// NewJSONListStream creates a new JSONListStream instance.
 func NewJSONListStream[T any](w http.ResponseWriter, r *http.Request, outerFieldName string) *JSONListStream[T] {
 	return &JSONListStream[T]{
 		OuterFieldName: outerFieldName,

internal/api/utils.go

@@ -22,7 +22,7 @@ func fromUnixEncodedTime(t limes.UnixEncodedTime) time.Time {
 	return t.Time
 }
 
-// Generates a token that is used to transfer a commitment from a source to a target project.
+// GenerateTransferToken generates a token that is used to transfer a commitment from a source to a target project.
 // The token will be attached to the commitment that will be transferred and stored in the database until the transfer is concluded.
 func GenerateTransferToken() string {
 	tokenBytes := make([]byte, 24)

internal/collector/consistency.go

@@ -20,6 +20,9 @@ import (
 	"github.com/sapcc/limes/internal/db"
 )
 
+// CheckConsistencyJob returns a jobloop.Job that periodically ensures that all
+// services which exist in the configuration exist in the database and that
+// project_services are fully populated in the database.
 func (c *Collector) CheckConsistencyJob(registerer prometheus.Registerer) jobloop.Job {
 	return (&jobloop.CronJob{
 		Metadata: jobloop.JobMetadata{

internal/collector/mail_delivery.go

@@ -17,6 +17,7 @@ import (
 	"github.com/sapcc/limes/internal/db"
 )
 
+// MailRequest is an interface for posting to the mail API.
 type MailRequest struct {
 	ProjectID string `json:"project_id"`
 	Subject   string `json:"subject"`

internal/collector/metrics.go

@@ -340,7 +340,7 @@ type DataMetricsReporter struct {
 	ReportZeroes bool
 }
 
-// This is the same Content-Type that promhttp's GET /metrics implementation reports.
+// ContentTypeForPrometheusMetrics is the same Content-Type that promhttp's GET /metrics implementation reports.
 // If this changes because of a prometheus/client-go upgrade, we will know because our
 // test verifies that promhttp yields this Content-Type. In the case of a change,
 // the output format of promhttp should be carefully reviewed for changes, and then
@@ -841,6 +841,7 @@ func newResourceAndRateBehaviorCache(cluster *core.Cluster) resourceAndRateBehav
 	return resourceAndRateBehaviorCache{cluster, cache, rateCache, cbCache}
 }
 
+// Get returns the cached ResourceBehavior for the given service type and resource name.
 func (c resourceAndRateBehaviorCache) Get(srvType db.ServiceType, resName liquid.ResourceName) core.ResourceBehavior {
 	if c.cache[srvType] == nil {
 		c.cache[srvType] = make(map[liquid.ResourceName]core.ResourceBehavior)
@@ -853,6 +854,7 @@ func (c resourceAndRateBehaviorCache) Get(srvType db.ServiceType, resName liquid
 	return behavior
 }
 
+// GetForRate returns the cached RateBehavior for the given service type and rate name.
 func (c resourceAndRateBehaviorCache) GetForRate(srvType db.ServiceType, rateName liquid.RateName) core.RateBehavior {
 	if c.rateCache[srvType] == nil {
 		c.rateCache[srvType] = make(map[liquid.RateName]core.RateBehavior)
@@ -865,6 +867,7 @@ func (c resourceAndRateBehaviorCache) GetForRate(srvType db.ServiceType, rateNam
 	return behavior
 }
 
+// GetCommitmentBehavior returns the cached ScopedCommitmentBehavior for the given service type and resource name.
 func (c resourceAndRateBehaviorCache) GetCommitmentBehavior(srvType db.ServiceType, resName liquid.ResourceName) core.ScopedCommitmentBehavior {
 	if c.cbCache[srvType] == nil {
 		c.cbCache[srvType] = make(map[liquid.ResourceName]core.ScopedCommitmentBehavior)

internal/datamodel/allocation_stats.go

@@ -56,6 +56,9 @@ func (c clusterAZAllocationStats) allowsQuotaOvercommit(cfg core.AutogrowQuotaDi
 	}
 }
 
+// CanAcceptCommitmentChanges determines whether the given commitment additions
+// and subtractions can be accepted in this resources AZ capacity, which already
+// considers the overcommit factor for the resource.
 func (c clusterAZAllocationStats) CanAcceptCommitmentChanges(additions, subtractions map[db.ProjectID]uint64, behavior core.CommitmentBehavior) bool {
 	// calculate `sum_over_projects(max(committed, usage))` before and after the requested changes
 	var (