Ftr: add comment for cluster

cluster/cluster.go

@@ -21,7 +21,8 @@ import (
 	"github.com/apache/dubbo-go/protocol"
 )
 
-// Cluster ...
+// Cluster
+//Extension - Cluster
 type Cluster interface {
 	Join(Directory) protocol.Invoker
 }

cluster/cluster_impl/available_cluster.go

@@ -31,7 +31,9 @@ func init() {
 	extension.SetCluster(available, NewAvailableCluster)
 }
 
-// NewAvailableCluster ...
+// NewAvailableCluster returns cluster instance
+//
+// Obtain available service providers
 func NewAvailableCluster() cluster.Cluster {
 	return &availableCluster{}
 }

cluster/cluster_impl/available_cluster_invoker.go

@@ -35,7 +35,7 @@ type availableClusterInvoker struct {
 	baseClusterInvoker
 }
 
-// NewAvailableClusterInvoker ...
+// NewAvailableClusterInvoker returns cluster invoker instance
 func NewAvailableClusterInvoker(directory cluster.Directory) protocol.Invoker {
 	return &availableClusterInvoker{
 		baseClusterInvoker: newBaseClusterInvoker(directory),

cluster/cluster_impl/broadcast_cluster.go

@@ -31,7 +31,10 @@ func init() {
 	extension.SetCluster(broadcast, NewBroadcastCluster)
 }
 
-// NewBroadcastCluster ...
+// NewBroadcastCluster returns broadcast cluster instance
+//
+// Calling all providers broadcast, one by one call, any error is reported.
+// It is usually used to notify all providers to update local resource information such as caches or logs.
 func NewBroadcastCluster() cluster.Cluster {
 	return &broadcastCluster{}
 }

cluster/cluster_impl/failback_cluster.go

@@ -31,7 +31,10 @@ func init() {
 	extension.SetCluster(failback, NewFailbackCluster)
 }
 
-// NewFailbackCluster ...
+// NewFailbackCluster returns failback cluster instance
+//
+// Failure automatically restored, failed to record the background request,
+// regular retransmission. Usually used for message notification operations.
 func NewFailbackCluster() cluster.Cluster {
 	return &failbackCluster{}
 }

cluster/cluster_impl/failfast_cluster.go

@@ -31,7 +31,10 @@ func init() {
 	extension.SetCluster(failfast, NewFailFastCluster)
 }
 
-// NewFailFastCluster ...
+// NewFailFastCluster returns failfast cluster instance
+//
+// Fast failure, only made a call, failure immediately error. Usually used for non-idempotent write operations,
+// such as adding records.
 func NewFailFastCluster() cluster.Cluster {
 	return &failfastCluster{}
 }

cluster/cluster_impl/failover_cluster.go

@@ -31,7 +31,11 @@ func init() {
 	extension.SetCluster(name, NewFailoverCluster)
 }
 
-// NewFailoverCluster ...
+// NewFailoverCluster returns failover cluster instance
+//
+// Failure automatically switch, when there is failure,
+// retry the other server (default). Usually used for read operations,
+// but retries can result in longer delays.
 func NewFailoverCluster() cluster.Cluster {
 	return &failoverCluster{}
 }

cluster/cluster_impl/failsafe_cluster.go

@@ -31,7 +31,9 @@ func init() {
 	extension.SetCluster(failsafe, NewFailsafeCluster)
 }
 
-// NewFailsafeCluster ...
+// NewFailsafeCluster returns failsafe cluster instance
+//
+// Failure of security, anomalies, directly ignored. Usually used to write audit logs and other operations.
 func NewFailsafeCluster() cluster.Cluster {
 	return &failsafeCluster{}
 }

cluster/cluster_impl/forking_cluster.go

@@ -31,7 +31,10 @@ func init() {
 	extension.SetCluster(forking, NewForkingCluster)
 }
 
-// NewForkingCluster ...
+// NewForkingCluster returns forking cluster instance
+//
+// Multiple servers are invoked in parallel, returning as soon as one succeeds.
+// Usually used for real-time demanding read operations, but need to waste more service resources.
 func NewForkingCluster() cluster.Cluster {
 	return &forkingCluster{}
 }

cluster/cluster_impl/mock_cluster.go

@@ -24,7 +24,11 @@ import (
 
 type mockCluster struct{}
 
-// NewMockCluster ...
+// NewMockCluster returns mock cluster instance
+//
+// Mock cluster is usually used for service degradation, such as an authentication service.
+// When the service provider is completely hung up, the client does not throw an exception,
+// but returns the authorization failure through the Mock data.
 func NewMockCluster() cluster.Cluster {
 	return &mockCluster{}
 }

cluster/cluster_impl/registry_aware_cluster.go

@@ -29,7 +29,7 @@ func init() {
 	extension.SetCluster("registryAware", NewRegistryAwareCluster)
 }
 
-// NewRegistryAwareCluster ...
+// NewRegistryAwareCluster returns registry aware cluster instance
 func NewRegistryAwareCluster() cluster.Cluster {
 	return &registryAwareCluster{}
 }

cluster/loadbalance/consistent_hash.go

@@ -60,6 +60,8 @@ type ConsistentHashLoadBalance struct {
 }
 
 // NewConsistentHashLoadBalance creates NewConsistentHashLoadBalance
+//
+// The same parameters of the request is always sent to the same provider.
 func NewConsistentHashLoadBalance() cluster.LoadBalance {
 	return &ConsistentHashLoadBalance{}
 }

cluster/loadbalance/least_active.go

@@ -28,7 +28,6 @@ import (
 )
 
 const (
-	// LeastActive ...
 	LeastActive = "leastactive"
 )
 
@@ -39,7 +38,9 @@ func init() {
 type leastActiveLoadBalance struct {
 }
 
-// NewLeastActiveLoadBalance ...
+// NewLeastActiveLoadBalance returns least active load balance
+//
+// A random mechanism based on actives, actives means the num of requests a consumer have sent but not return yet
 func NewLeastActiveLoadBalance() cluster.LoadBalance {
 	return &leastActiveLoadBalance{}
 }

cluster/loadbalance/random.go

@@ -38,7 +38,9 @@ func init() {
 type randomLoadBalance struct {
 }
 
-// NewRandomLoadBalance ...
+// NewRandomLoadBalance returns random load balance instance
+//
+// Set random probabilities by weight, the request sent to provider is random
 func NewRandomLoadBalance() cluster.LoadBalance {
 	return &randomLoadBalance{}
 }

cluster/loadbalance/round_robin.go

@@ -52,7 +52,9 @@ func init() {
 
 type roundRobinLoadBalance struct{}
 
-// NewRoundRobinLoadBalance ...
+// NewRoundRobinLoadBalance returns round robin load balance
+//
+// Use the weight's common advisory to determine round robin ratio
 func NewRoundRobinLoadBalance() cluster.LoadBalance {
 	return &roundRobinLoadBalance{}
 }

cluster/loadbalance/util.go

@@ -26,7 +26,7 @@ import (
 	"github.com/apache/dubbo-go/protocol"
 )
 
-// GetWeight ...
+// GetWeight gets weight for load balance strategy
 func GetWeight(invoker protocol.Invoker, invocation protocol.Invocation) int64 {
 	url := invoker.GetUrl()
 	weight := url.GetMethodParamInt64(invocation.MethodName(), constant.WEIGHT_KEY, constant.DEFAULT_WEIGHT)