Update go docs of flow/isolation/system/circuitbreaker packages

Signed-off-by: Eric Zhao <[email protected]>

Author: sczyh30

core/circuitbreaker/doc.go

@@ -12,9 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package circuitbreaker implements the circuit breaker.
-//
-// Sentinel circuit breaker module converts each Rule into a CircuitBreaker. Each CircuitBreaker has its own statistical structure.
+// Package circuitbreaker implements the circuit breaker pattern, which provides
+// stability and prevents cascading failures in distributed systems.
 //
 // Sentinel circuit breaker module supports three strategies:
 //
@@ -23,13 +22,15 @@
 //  2. ErrorRatio: the ratio of error entry exceeds the threshold. The following entry to resource will be broken.
 //  3. ErrorCount: the number of error entry exceeds the threshold. The following entry to resource will be broken.
 //
-// Sentinel circuit breaker is implemented based on state machines. There are three state:
+// Sentinel converts each circuit breaking Rule into a CircuitBreaker. Each CircuitBreaker has its own statistical structure.
+//
+// Sentinel circuit breaker is implemented based on state machines. There are three states:
 //
 //  1. Closed: all entries could pass checking.
 //  2. Open: the circuit breaker is broken, all entries are blocked. After retry timeout, circuit breaker switches state to Half-Open and allows one entry to probe whether the resource returns to its expected state.
 //  3. Half-Open: the circuit breaker is in a temporary state of probing, only one entry is allowed to access resource, others are blocked.
 //
-// Sentinel circuit breaker provides the listener to listen on the state changes.
+// Sentinel circuit breaker provides the listener to observe events of state changes.
 //
 //  type StateChangeListener interface {
 //  	OnTransformToClosed(prev State, rule Rule)

core/flow/rule.go

@@ -63,10 +63,12 @@ func (s TokenCalculateStrategy) String() string {
 	}
 }
 
+// ControlBehavior defines the behavior when requests have reached the capacity of the resource.
 type ControlBehavior int32
 
 const (
 	Reject ControlBehavior = iota
+	// Throttling indicates that pending requests will be throttled, wait in queue (until free capacity is available)
 	Throttling
 )
 

core/isolation/rule.go

@@ -23,7 +23,7 @@ import (
 type MetricType int32
 
 const (
-	// Concurrency represents concurrency count.
+	// Concurrency represents concurrency (in-flight requests).
 	Concurrency MetricType = iota
 )
 
@@ -36,11 +36,14 @@ func (s MetricType) String() string {
 	}
 }
 
-// Rule describes the concurrency num control, that is similar to semaphore
+// Rule describes the isolation policy (e.g. semaphore isolation).
 type Rule struct {
 	// ID represents the unique ID of the rule (optional).
-	ID         string     `json:"id,omitempty"`
-	Resource   string     `json:"resource"`
+	ID string `json:"id,omitempty"`
+	// Resource represents the target resource definition.
+	Resource string `json:"resource"`
+	// MetricType indicates the metric type for checking logic.
+	// Currently Concurrency is supported for concurrency limiting.
 	MetricType MetricType `json:"metricType"`
 	Threshold  uint32     `json:"threshold"`
 }

core/system/rule.go

@@ -28,8 +28,11 @@ const (
 	AvgRT
 	// Concurrency represents the concurrency of all inbound requests.
 	Concurrency
+	// InboundQPS represents the QPS of all inbound requests.
 	InboundQPS
+	// CpuUsage represents the CPU usage percentage of the system.
 	CpuUsage
+
 	// MetricTypeSize indicates the enum size of MetricType.
 	MetricTypeSize
 )
@@ -55,7 +58,7 @@ type AdaptiveStrategy int32
 
 const (
 	NoAdaptive AdaptiveStrategy = -1
-	// 1
+	// BBR represents the adaptive strategy based on ideas of TCP BBR.
 	BBR AdaptiveStrategy = iota
 )
 
@@ -70,11 +73,17 @@ func (t AdaptiveStrategy) String() string {
 	}
 }
 
+// Rule describes the policy for system resiliency.
 type Rule struct {
-	ID           string           `json:"id,omitempty"`
-	MetricType   MetricType       `json:"metricType"`
-	TriggerCount float64          `json:"triggerCount"`
-	Strategy     AdaptiveStrategy `json:"strategy"`
+	// ID represents the unique ID of the rule (optional).
+	ID string `json:"id,omitempty"`
+	// MetricType indicates the type of the trigger metric.
+	MetricType MetricType `json:"metricType"`
+	// TriggerCount represents the lower bound trigger of the adaptive strategy.
+	// Adaptive strategies will not be activated until target metric has reached the trigger count.
+	TriggerCount float64 `json:"triggerCount"`
+	// Strategy represents the adaptive strategy.
+	Strategy AdaptiveStrategy `json:"strategy"`
 }
 
 func (r *Rule) String() string {