liquid: add links in docstrings

To make it easier to navigate up and down the type hierarchy.

Author: majewsky

liquid/commitment.go

@@ -62,7 +62,7 @@ func (r CommitmentChangeResponse) Clone() CommitmentChangeResponse {
 	return r
 }
 
-// ProjectCommitmentChangeset appears in type CommitmentChangeRequest.
+// ProjectCommitmentChangeset appears in type [CommitmentChangeRequest].
 // It contains all commitments that are part of a single atomic changeset that belong to a specific project in a specific AZ.
 type ProjectCommitmentChangeset struct {
 	// Metadata about the project from Keystone.
@@ -83,7 +83,7 @@ func (c ProjectCommitmentChangeset) Clone() ProjectCommitmentChangeset {
 	return cloned
 }
 
-// ResourceCommitmentChangeset appears in type CommitmentChangeRequest.
+// ResourceCommitmentChangeset appears in type [CommitmentChangeRequest].
 // It contains all commitments that are part of a single atomic changeset that belong to a given resource within a specific project and AZ.
 type ResourceCommitmentChangeset struct {
 	// The sum of all commitments in CommitmentStatusConfirmed for the given resource, project and AZ before and after applying the proposed commitment changeset.
@@ -111,10 +111,10 @@ func (c ResourceCommitmentChangeset) Clone() ResourceCommitmentChangeset {
 	return cloned
 }
 
-// Commitment appears in type CommitmentChangeRequest.
+// Commitment appears in type [CommitmentChangeRequest].
 //
 // The commitment is located in a certain project and applies to a certain resource within a certain AZ.
-// These metadata are implied by where the commitment is found within type CommitmentChangeRequest.
+// These metadata are implied by where the commitment is found within type [CommitmentChangeRequest].
 type Commitment struct {
 	// The same UUID may appear multiple times within the same changeset for one specific circumstance:
 	// If a commitment moves between projects, it will appear as being deleted in the source project and again as being created in the target project.
@@ -151,7 +151,7 @@ func (c Commitment) Clone() Commitment {
 	return c
 }
 
-// CommitmentStatus is an enum containing the various lifecycle states of type Commitment.
+// CommitmentStatus is an enum containing the various lifecycle states of type [Commitment].
 // The following state transitions are allowed:
 //
 //	start = "planned" -> "pending" -> "confirmed"   // normal commitment that takes effect after the ConfirmBy date
@@ -196,7 +196,7 @@ func (s CommitmentStatus) IsValid() bool {
 }
 
 // RequiresConfirmation describes if this request requires confirmation from the liquid.
-// The RejectionReason in type CommitmentChangeResponse may only be used if this returns true.
+// The RejectionReason in type [CommitmentChangeResponse] may only be used if this returns true.
 //
 // Examples for RequiresConfirmation = true include commitments moving into or spawning in the "guaranteed" or "confirmed" statuses, or conversion of commitments between resources.
 // Examples for RequiresConfirmation = false include commitments being split, moving into the "expired" status or being hard deleted.

liquid/doc.go

@@ -108,34 +108,34 @@
 // # Endpoint: GET /v1/info
 //
 // Returns information about the OpenStack service and the resources available within it.
-//   - On success, the response body payload must be of type ServiceInfo.
+//   - On success, the response body payload must be of type [ServiceInfo].
 //
 // # Endpoint: POST /v1/report-capacity
 //
 // Reports available capacity across all resources of this service.
-//   - The request body payload must be of type ServiceCapacityRequest.
-//   - On success, the response body payload must be of type ServiceCapacityReport.
+//   - The request body payload must be of type [ServiceCapacityRequest].
+//   - On success, the response body payload must be of type [ServiceCapacityReport].
 //
 // # Endpoint: POST /v1/projects/:uuid/report-usage
 //
 // Reports usage data (as well as applicable quotas) within a project across all resources of this service.
 //   - The ":uuid" parameter in the request path must refer to a project ID known to Keystone.
-//   - The request body payload must be of type ServiceUsageRequest.
-//   - On success, the response body payload must be of type ServiceUsageReport.
+//   - The request body payload must be of type [ServiceUsageRequest].
+//   - On success, the response body payload must be of type [ServiceUsageReport].
 //
 // # Endpoint: PUT /v1/projects/:uuid/quota
 //
 // Updates quota within a project across all resources of this service.
 //   - The ":uuid" parameter in the request path must refer to a project ID known to Keystone.
-//   - The request body payload must be of type ServiceQuotaRequest.
+//   - The request body payload must be of type [ServiceQuotaRequest].
 //   - On success, the response body shall be empty and status 204 (No Content) shall be returned.
 //
 // # Endpoint: POST /v1/change-commitments
 //
 // Notifies the liquid about changes to commitments that it is interested in.
 // Commitments for different projects and different resources may be batched together if they are all part of the same atomic change.
-//   - The request body payload must be of type CommitmentChangeRequest.
-//   - On success, the response body payload must be of type CommitmentChangeResponse.
+//   - The request body payload must be of type [CommitmentChangeRequest].
+//   - On success, the response body payload must be of type [CommitmentChangeResponse].
 //
 // [Limes]: https://github.com/sapcc/limes
 // [OpenMetrics format]: https://github.com/OpenObservability/OpenMetrics/blob/master/specification/OpenMetrics.md

liquid/info.go

@@ -68,7 +68,7 @@ func (i ServiceInfo) Clone() ServiceInfo {
 }
 
 // CategoryName is a name of a category that can group resources and rates.
-// It appears in type ServiceInfo, ResourceInfo and RateInfo.
+// It appears in type [ServiceInfo], [ResourceInfo] and [RateInfo].
 type CategoryName string
 
 // IsValid returns whether a CategoryName is valid.
@@ -78,7 +78,7 @@ func (c CategoryName) IsValid() bool {
 }
 
 // CategoryInfo describes a category that can group resources and rates of a liquid's service.
-// This type appears in type ServiceInfo.
+// This type appears in type [ServiceInfo].
 type CategoryInfo struct {
 	DisplayName string `json:"displayName"`
 }
@@ -91,7 +91,7 @@ func (c CategoryInfo) Clone() CategoryInfo {
 }
 
 // ResourceInfo describes a resource that a liquid's service provides.
-// This type appears in type ServiceInfo.
+// This type appears in type [ServiceInfo].
 type ResourceInfo struct {
 	// The display name can be used in user-facing messages or interfaces to refer to the resource.
 	DisplayName string `json:"displayName"`
@@ -141,7 +141,7 @@ func (i ResourceInfo) Clone() ResourceInfo {
 }
 
 // Topology describes how capacity and usage reported by a certain resource is structured.
-// It appears in type ResourceInfo.
+// It appears in type [ResourceInfo].
 type Topology string
 
 const (
@@ -218,7 +218,7 @@ func (t Topology) IsValid() bool {
 }
 
 // RateInfo describes a rate that a liquid's service provides.
-// This type appears in type ServiceInfo.
+// This type appears in type [ServiceInfo].
 type RateInfo struct {
 	// The display name can be used in user-facing messages or interfaces to refer to the rate.
 	DisplayName string `json:"displayName"`
@@ -251,7 +251,7 @@ func (i RateInfo) Clone() RateInfo {
 
 // ProjectMetadata includes metadata about a project from Keystone.
 //
-// It appears in types ServiceUsageRequest and ServiceQuotaRequest if requested by the ServiceInfo.
+// It appears in types [ServiceUsageRequest] and [ServiceQuotaRequest] if requested by the [ServiceInfo].
 type ProjectMetadata struct {
 	UUID   string         `json:"uuid"`
 	Name   string         `json:"name"`
@@ -260,7 +260,7 @@ type ProjectMetadata struct {
 
 // DomainMetadata includes metadata about a domain from Keystone.
 //
-// It appears in type ProjectMetadata.
+// It appears in type [ProjectMetadata].
 type DomainMetadata struct {
 	UUID string `json:"uuid"`
 	Name string `json:"name"`

liquid/metrics.go

@@ -25,7 +25,7 @@ const (
 )
 
 // MetricFamilyInfo describes a metric family.
-// This type appears in type ServiceInfo.
+// This type appears in type [ServiceInfo].
 // For more information, please refer to the "Metrics" section of the package documentation.
 type MetricFamilyInfo struct {
 	// The metric type.
@@ -48,15 +48,15 @@ func (i MetricFamilyInfo) Clone() MetricFamilyInfo {
 }
 
 // Metric is a metric.
-// This type appears in type ServiceCapacityReport.
+// This type appears in type [ServiceCapacityReport].
 // For more information, please refer to the "Metrics" section of the package documentation.
 //
 // Because reports can include very large numbers of Metric instances, this type uses a compact serialization to improve efficiency.
 type Metric struct {
 	Value float64 `json:"v"`
 
 	// This label set does not include keys to avoid redundant encoding.
-	// The slice must be of the same length as the LabelKeys slice in the respective MetricFamilyInfo instance in type ServiceInfo.
+	// The slice must be of the same length as the LabelKeys slice in the respective [MetricFamilyInfo] instance in type [ServiceInfo].
 	// Each label value is implied to belong to the label key with the same slice index.
 	// For example, LabelKeys = ["name","location"] and LabelValues = ["author","work"] represents the label set {name="author",location="work"}.
 	LabelValues []string `json:"l"`

liquid/overcommit_factor.go

@@ -4,7 +4,7 @@
 package liquid
 
 // OvercommitFactor is the ratio between raw and effective capacity of a resource.
-// It appears in type ResourceDemand.
+// It appears in type [ResourceDemand].
 //
 // In its methods, the zero value behaves as 1, meaning that no overcommit is taking place.
 type OvercommitFactor float64

liquid/quota.go

@@ -26,7 +26,7 @@ func (i ServiceQuotaRequest) Clone() ServiceQuotaRequest {
 }
 
 // ResourceQuotaRequest contains new quotas for a single resource.
-// It appears in type ServiceQuotaRequest.
+// It appears in type [ServiceQuotaRequest].
 type ResourceQuotaRequest struct {
 	// For FlatTopology and AZAwareTopology, this is the only field that is filled, and PerAZ will be nil.
 	// For AZSeparatedTopology, this contains the sum of the quotas across all AZs (for compatibility purposes).
@@ -44,7 +44,7 @@ func (i ResourceQuotaRequest) Clone() ResourceQuotaRequest {
 }
 
 // AZResourceQuotaRequest contains the new quota value for a single resource and AZ.
-// It appears in type ResourceQuotaRequest.
+// It appears in type [ResourceQuotaRequest].
 type AZResourceQuotaRequest struct {
 	Quota uint64 `json:"quota"`
 

liquid/report_capacity.go

@@ -20,7 +20,7 @@ type ServiceCapacityRequest struct {
 	// Limes provides this list here to reduce the number of places where this information needs to be maintained manually.
 	AllAZs []AvailabilityZone `json:"allAZs"`
 
-	// Must contain an entry for each resource that was declared in type ServiceInfo with "NeedsResourceDemand = true".
+	// Must contain an entry for each resource that was declared in type [ServiceInfo] with "NeedsResourceDemand = true".
 	DemandByResource map[ResourceName]ResourceDemand `json:"demandByResource"`
 }
 
@@ -33,7 +33,7 @@ func (r ServiceCapacityRequest) Clone() ServiceCapacityRequest {
 }
 
 // ResourceDemand contains demand statistics for a resource.
-// It appears in type ServiceCapacityRequest.
+// It appears in type [ServiceCapacityRequest].
 //
 // This is used when a liquid needs to be able to reshuffle capacity between different resources based on actual user demand.
 type ResourceDemand struct {
@@ -54,7 +54,7 @@ func (d ResourceDemand) Clone() ResourceDemand {
 }
 
 // ResourceDemandInAZ contains demand statistics for a resource in a single AZ.
-// It appears in type ResourceDemand.
+// It appears in type [ResourceDemand].
 //
 // The fields are ordered in descending priority.
 // All values are in terms of effective capacity, and are sums over all OpenStack projects.
@@ -82,10 +82,10 @@ type ServiceCapacityReport struct {
 	// This is used to signal to Limes to refetch GET /v1/info after configuration changes.
 	InfoVersion int64 `json:"infoVersion"`
 
-	// Must contain an entry for each resource that was declared in type ServiceInfo with "HasCapacity = true".
+	// Must contain an entry for each resource that was declared in type [ServiceInfo] with "HasCapacity = true".
 	Resources map[ResourceName]*ResourceCapacityReport `json:"resources,omitempty"`
 
-	// Must contain an entry for each metric family that was declared for capacity metrics in type ServiceInfo.
+	// Must contain an entry for each metric family that was declared for capacity metrics in type [ServiceInfo].
 	Metrics map[MetricName][]Metric `json:"metrics,omitempty"`
 }
 
@@ -98,7 +98,7 @@ func (r ServiceCapacityReport) Clone() ServiceCapacityReport {
 }
 
 // ResourceCapacityReport contains capacity data for a resource.
-// It appears in type ServiceCapacityReport.
+// It appears in type [ServiceCapacityReport].
 type ResourceCapacityReport struct {
 	// The keys that are allowed in this map depend on the chosen Topology.
 	// See documentation on Topology enum variants for details.
@@ -113,7 +113,7 @@ func (r ResourceCapacityReport) Clone() ResourceCapacityReport {
 }
 
 // AZResourceCapacityReport contains capacity data for a resource in a single AZ.
-// It appears in type ResourceCapacityReport.
+// It appears in type [ResourceCapacityReport].
 type AZResourceCapacityReport struct {
 	// How much capacity is available to Limes in this resource and AZ.
 	//

liquid/report_usage.go

@@ -27,7 +27,7 @@ type ServiceUsageRequest struct {
 	ProjectMetadata Option[ProjectMetadata] `json:"projectMetadata,omitzero"`
 
 	// The serialized state from the previous ServiceUsageReport received by Limes for this project, if any.
-	// Refer to the same field on type ServiceUsageReport for details.
+	// Refer to the same field on type [ServiceUsageReport] for details.
 	SerializedState json.RawMessage `json:"serializedState,omitempty"`
 }
 
@@ -45,13 +45,13 @@ type ServiceUsageReport struct {
 	// This is used to signal to Limes to refetch GET /v1/info after configuration changes.
 	InfoVersion int64 `json:"infoVersion"`
 
-	// Must contain an entry for each resource that was declared in type ServiceInfo.
+	// Must contain an entry for each resource that was declared in type [ServiceInfo].
 	Resources map[ResourceName]*ResourceUsageReport `json:"resources,omitempty"`
 
-	// Must contain an entry for each rate that was declared in type ServiceInfo.
+	// Must contain an entry for each rate that was declared in type [ServiceInfo].
 	Rates map[RateName]*RateUsageReport `json:"rates,omitempty"`
 
-	// Must contain an entry for each metric family that was declared for usage metrics in type ServiceInfo.
+	// Must contain an entry for each metric family that was declared for usage metrics in type [ServiceInfo].
 	Metrics map[MetricName][]Metric `json:"metrics,omitempty"`
 
 	// Opaque state for Limes to persist and return to the liquid in the next ServiceUsageRequest for the same project.
@@ -76,7 +76,7 @@ func (r ServiceUsageReport) Clone() ServiceUsageReport {
 }
 
 // ResourceUsageReport contains usage data for a resource in a single project.
-// It appears in type ServiceUsageReport.
+// It appears in type [ServiceUsageReport].
 type ResourceUsageReport struct {
 	// If true, this project is forbidden from accessing this resource.
 	// This has two consequences:
@@ -103,7 +103,7 @@ func (r ResourceUsageReport) Clone() ResourceUsageReport {
 }
 
 // AZResourceUsageReport contains usage data for a resource in a single project and AZ.
-// It appears in type ResourceUsageReport.
+// It appears in type [ResourceUsageReport].
 type AZResourceUsageReport struct {
 	// The amount of usage for this resource.
 	Usage uint64 `json:"usage"`
@@ -169,7 +169,7 @@ func (r *ResourceUsageReport) AddLocalizedUsage(az AvailabilityZone, usage uint6
 }
 
 // RateUsageReport contains usage data for a rate in a single project.
-// It appears in type ServiceUsageReport.
+// It appears in type [ServiceUsageReport].
 type RateUsageReport struct {
 	// The keys that are allowed in this map depend on the chosen Topology.
 	// See documentation on Topology enum variants for details.
@@ -184,14 +184,14 @@ func (r RateUsageReport) Clone() RateUsageReport {
 }
 
 // AZRateUsageReport contains usage data for a rate in a single project and AZ.
-// It appears in type RateUsageReport.
+// It appears in type [RateUsageReport].
 type AZRateUsageReport struct {
 	// The amount of usage for this rate. Must be Some() and non-nil if the rate is declared with HasUsage = true.
 	// The value Some(nil) is forbidden.
 	//
 	// For a given rate, project and AZ, this value must only ever increase monotonically over time.
 	// If there is the possibility of counter resets or limited retention in the underlying data source, the liquid must add its own logic to guarantee monotonicity.
-	// A common strategy is to remember previous measurements in the SerializedState field of type ServiceUsageReport.
+	// A common strategy is to remember previous measurements in the SerializedState field of type [ServiceUsageReport].
 	//
 	// This field is modeled as a bigint because network rates like "bytes transferred" may easily exceed the range of uint64 over time.
 	Usage Option[*big.Int] `json:"usage,omitzero"`

liquid/subdivisions.go

@@ -11,7 +11,7 @@ import (
 )
 
 // Subcapacity describes a distinct chunk of capacity for a resource within an AZ.
-// It appears in type AZResourceCapacityReport.
+// It appears in type [AZResourceCapacityReport].
 //
 // A service will only report subcapacities for such resources where there is a useful substructure to report.
 // For example:
@@ -49,7 +49,7 @@ func (s Subcapacity) Clone() Subcapacity {
 	return cloned
 }
 
-// SubcapacityBuilder is a helper type for building Subcapacity values.
+// SubcapacityBuilder is a helper type for building [Subcapacity] values.
 // If the Attributes in a subcapacity are collected over time, it might be more convenient to have them accessible as a structured type.
 // Once assembly is complete, the provided methods can be used to obtain the final Subcapacity value.
 type SubcapacityBuilder[A any] struct {
@@ -74,7 +74,7 @@ func (b SubcapacityBuilder[A]) Finalize() (Subcapacity, error) {
 }
 
 // Subresource describes a distinct chunk of usage for a resource within a project and AZ.
-// It appears in type AZResourceUsageReport.
+// It appears in type [AZResourceUsageReport].
 //
 // A service will only report subresources for such resources where there is a useful substructure to report.
 // For example, in the Nova resource "instances", each instance is a subresource.
@@ -105,7 +105,7 @@ func (s Subresource) Clone() Subresource {
 	return cloned
 }
 
-// SubresourceBuilder is a helper type for building Subresource values.
+// SubresourceBuilder is a helper type for building [Subresource] values.
 // If the Attributes in a subresource are collected over time, it might be more convenient to have them accessible as a structured type.
 // Once assembly is complete, the provided methods can be used to obtain the final Subresource value.
 type SubresourceBuilder[A any] struct {