Go CRD Comment Updates for Counters and Lists (#3536)

Updated some comments on the Counter and Lists with an aim to make the
generated reference document more readable and provide more context of
the operations therein.

Work on #2716

Author: markmandel

pkg/apis/agones/v1/common.go

@@ -174,12 +174,12 @@ func (ao *AllocationOverflow) Apply(gs *GameServer) {
 }
 
 // Priority is a sorting option for GameServers with Counters or Lists based on the Capacity.
-// Type: Sort by a "Counter" or a "List".
-// Key: The name of the Counter or List. If not found on the GameServer, has no impact.
-// Order: Sort by "Ascending" or "Descending". "Descending" a bigger Capacity is preferred.
-// "Ascending" would be smaller Capacity is preferred.
 type Priority struct {
-	Type  string `json:"type"`
-	Key   string `json:"key"`
+	// Type: Sort by a "Counter" or a "List".
+	Type string `json:"type"`
+	// Key: The name of the Counter or List. If not found on the GameServer, has no impact.
+	Key string `json:"key"`
+	// Order: Sort by "Ascending" or "Descending". "Descending" a bigger Capacity is preferred.
+	// "Ascending" would be smaller Capacity is preferred.
 	Order string `json:"order"`
 }

pkg/apis/agones/v1/gameserver.go

@@ -213,10 +213,14 @@ type GameServerSpec struct {
 	// (Alpha, PlayerTracking feature flag) Players provides the configuration for player tracking features.
 	// +optional
 	Players *PlayersSpec `json:"players,omitempty"`
-	// (Alpha, CountsAndLists feature flag) Counters and Lists provides the configuration for generic tracking features.
+	// (Alpha, CountsAndLists feature flag) Counters provides the configuration for tracking of int64 values against a GameServer.
+	// Keys must be declared at GameServer creation time.
 	// +optional
 	Counters map[string]CounterStatus `json:"counters,omitempty"`
-	Lists    map[string]ListStatus    `json:"lists,omitempty"`
+	// (Alpha, CountsAndLists feature flag) Lists provides the configuration for tracking of lists of up to 1000 values against a GameServer.
+	// Keys must be declared at GameServer creation time.
+	// +optional
+	Lists map[string]ListStatus `json:"lists,omitempty"`
 	// Eviction specifies the eviction tolerance of the GameServer. Defaults to "Never".
 	// +optional
 	Eviction *Eviction `json:"eviction,omitempty"`
@@ -321,13 +325,13 @@ type PlayerStatus struct {
 	IDs      []string `json:"ids"`
 }
 
-// CounterStatus stores the current counter values
+// CounterStatus stores the current counter values and maximum capacity
 type CounterStatus struct {
 	Count    int64 `json:"count"`
 	Capacity int64 `json:"capacity"`
 }
 
-// ListStatus stores the current list values
+// ListStatus stores the current list values and maximum capacity
 type ListStatus struct {
 	Capacity int64    `json:"capacity"`
 	Values   []string `json:"values"`

pkg/apis/allocation/v1/gameserverallocation.go

@@ -21,13 +21,13 @@ import (
 	"agones.dev/agones/pkg/apis"
 	agonesv1 "agones.dev/agones/pkg/apis/agones/v1"
 	"agones.dev/agones/pkg/util/runtime"
-	hashstructure "github.com/mitchellh/hashstructure/v2"
+	"github.com/mitchellh/hashstructure/v2"
 	corev1 "k8s.io/api/core/v1"
 	apivalidation "k8s.io/apimachinery/pkg/api/validation"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	metav1validation "k8s.io/apimachinery/pkg/apis/meta/v1/validation"
 	"k8s.io/apimachinery/pkg/labels"
-	field "k8s.io/apimachinery/pkg/util/validation/field"
+	"k8s.io/apimachinery/pkg/util/validation/field"
 )
 
 const (
@@ -105,11 +105,12 @@ type GameServerAllocationSpec struct {
 	// You can use this to tell the server necessary session data
 	MetaPatch MetaPatch `json:"metadata,omitempty" hash:"ignore"`
 
-	// (Alpha, CountsAndLists feature flag) Counters and Lists provide a set of actions to perform
-	// on Counters and Lists during allocation.
+	// (Alpha, CountsAndLists feature flag) Counter actions to perform during allocation.
 	// +optional
 	Counters map[string]CounterAction `json:"counters,omitempty" hash:"ignore"`
-	Lists    map[string]ListAction    `json:"lists,omitempty" hash:"ignore"`
+	// (Alpha, CountsAndLists feature flag) List actions to perform during allocation.
+	// +optional
+	Lists map[string]ListAction `json:"lists,omitempty" hash:"ignore"`
 }
 
 // GameServerSelector contains all the filter options for selecting
@@ -146,40 +147,56 @@ type PlayerSelector struct {
 }
 
 // CounterSelector is the filter options for a GameServer based on the count and/or available capacity.
-// 0 for MaxCount or MaxAvailable means unlimited maximum. Default for all fields: 0
 type CounterSelector struct {
-	MinCount     int64 `json:"minCount"`
-	MaxCount     int64 `json:"maxCount"`
+	// MinCount is the minimum current value. Defaults to 0.
+	// +optional
+	MinCount int64 `json:"minCount"`
+	// MaxCount is the maximum current value. Defaults to 0, which translates as max(in64).
+	// +optional
+	MaxCount int64 `json:"maxCount"`
+	// MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
+	// +optional
 	MinAvailable int64 `json:"minAvailable"`
+	// MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which translates to max(int64).
+	// +optional
 	MaxAvailable int64 `json:"maxAvailable"`
 }
 
 // ListSelector is the filter options for a GameServer based on List available capacity and/or the
 // existence of a value in a List.
-// 0 for MaxAvailable means unlimited maximum. Default for integer fields: 0
-// "" for ContainsValue means ignore field. Default for string field: ""
 type ListSelector struct {
+	// ContainsValue says to only match GameServers who has this value in the list. Defaults to "", which is all.
+	// +optional
 	ContainsValue string `json:"containsValue"`
-	MinAvailable  int64  `json:"minAvailable"`
-	MaxAvailable  int64  `json:"maxAvailable"`
+	// MinAvailable specifies the minimum capacity (current capacity - current count) available on a GameServer. Defaults to 0.
+	// +optional
+	MinAvailable int64 `json:"minAvailable"`
+	// MaxAvailable specifies the maximum capacity (current capacity - current count) available on a GameServer. Defaults to 0, which is translated as max(int64).
+	// +optional
+	MaxAvailable int64 `json:"maxAvailable"`
 }
 
 // CounterAction is an optional action that can be performed on a Counter at allocation.
-// Action: "Increment" or "Decrement" the Counter's Count (optional). Must also define the Amount.
-// Amount: The amount to increment or decrement the Count (optional). Must be a positive integer.
-// Capacity: Update the maximum capacity of the Counter to this number (optional). Min 0, Max int64.
 type CounterAction struct {
-	Action   *string `json:"action,omitempty"`
-	Amount   *int64  `json:"amount,omitempty"`
-	Capacity *int64  `json:"capacity,omitempty"`
+	// Action must to either "Increment" or "Decrement" the Counter's Count. Must also define the Amount.
+	// +optional
+	Action *string `json:"action,omitempty"`
+	// Amount is the amount to increment or decrement the Count. Must be a positive integer.
+	// +optional
+	Amount *int64 `json:"amount,omitempty"`
+	// Capacity is the amount to update the maximum capacity of the Counter to this number. Min 0, Max int64.
+	// +optional
+	Capacity *int64 `json:"capacity,omitempty"`
 }
 
 // ListAction is an optional action that can be performed on a List at allocation.
-// AddValues: Append values to a List's Values array (optional). Any duplicate values will be ignored.
-// Capacity: Update the maximum capacity of the Counter to this number (optional). Min 0, Max 1000.
 type ListAction struct {
+	// AddValues appends values to a List's Values array. Any duplicate values will be ignored.
+	// +optional
 	AddValues []string `json:"addValues,omitempty"`
-	Capacity  *int64   `json:"capacity,omitempty"`
+	// Capacity updates the maximum capacity of the Counter to this number. Min 0, Max 1000.
+	// +optional
+	Capacity *int64 `json:"capacity,omitempty"`
 }
 
 // ApplyDefaults applies default values