Update documentation of several types

kubernetes-sigs · Jan 31, 2025 · 91c2f48 · 91c2f48
1 parent f8cdd8e
commit 91c2f48
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 6 deletions.
diff --git a/pkg/cache/clusterqueue_snapshot.go b/pkg/cache/clusterqueue_snapshot.go
@@ -134,12 +134,6 @@ func (c *ClusterQueueSnapshot) parentHRN() hierarchicalResourceNode {
 	return c.Parent()
 }
 
-// DominantResourceShare returns a value from 0 to 1,000,000 representing the maximum of the ratios
-// of usage above nominal quota to the lendable resources in the cohort, among all the resources
-// provided by the ClusterQueue, and divided by the weight.
-// If zero, it means that the usage of the ClusterQueue is below the nominal quota.
-// The function also returns the resource name that yielded this value.
-// Also for a weight of zero, this will return 9223372036854775807.
 func (c *ClusterQueueSnapshot) DominantResourceShare() (int, corev1.ResourceName) {
 	return dominantResourceShare(c, nil)
 }

diff --git a/pkg/cache/fair_sharing.go b/pkg/cache/fair_sharing.go
@@ -25,11 +25,20 @@ import (
 	"sigs.k8s.io/kueue/pkg/resources"
 )
 
+// dominantResourceShareNode is a node in the Cohort tree on which we
+// can compute its dominantResourceShare.
 type dominantResourceShareNode interface {
+	// see FairSharing.Weight in the API.
 	fairWeight() *resource.Quantity
 	hierarchicalResourceNode
 }
 
+// dominantResourceShare returns a value from 0 to 1,000,000 representing the maximum of the ratios
+// of usage above nominal quota to the lendable resources in the cohort, among all the resources
+// provided by the ClusterQueue, and divided by the weight.
+// If zero, it means that the usage of the ClusterQueue is below the nominal quota.
+// The function also returns the resource name that yielded this value.
+// Also for a weight of zero, this will return 9223372036854775807.
 func dominantResourceShare(node dominantResourceShareNode, wlReq resources.FlavorResourceQuantities) (int, corev1.ResourceName) {
 	if !node.HasParent() {
 		return 0, ""

diff --git a/pkg/cache/resource_node.go b/pkg/cache/resource_node.go
@@ -26,6 +26,8 @@ import (
 	"sigs.k8s.io/kueue/pkg/resources"
 )
 
+// ResourceNode is the shared representation of Quotas and Usage, used
+// by ClusterQueues and Cohorts.
 type ResourceNode struct {
 	// Quotas are the ResourceQuotas specified for the current
 	// node.
@@ -68,6 +70,9 @@ func (r ResourceNode) guaranteedQuota(fr resources.FlavorResource) int64 {
 	return 0
 }
 
+// hierarchicalResourceNode abstracts over ClusterQueues and Cohorts,
+// by providing access to the contained ResourceNode, with the ability
+// to navigate to the parent node.
 type hierarchicalResourceNode interface {
 	getResourceNode() ResourceNode