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 a 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 a 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 a broadcast cluster instance.
+//
+// Calling all providers' broadcast one by one. All errors will be 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 a 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 a 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 a failover cluster instance
+//
+// Failure automatically switch, when there is a 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,10 @@ func init() {
 	extension.SetCluster(failsafe, NewFailsafeCluster)
 }
 
-// NewFailsafeCluster ...
+// NewFailsafeCluster returns a failsafe cluster instance.
+//
+// Failure of security, anomalies, directly ignored. Usually it is
+// 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 a forking cluster instance.
+//
+// Multiple servers are invoked in parallel, returning as soon as one succeeds.
+// Usually it is used for real-time demanding read operations while wasting 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 a 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,
+// return an authorization failure through the Mock data instead.
 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 a registry aware cluster instance
 func NewRegistryAwareCluster() cluster.Cluster {
 	return &registryAwareCluster{}
 }

cluster/directory.go

@@ -23,7 +23,7 @@ import (
 )
 
 // Directory
-//Extension - Directory
+// Extension - Directory
 type Directory interface {
 	common.Node
 	List(invocation protocol.Invocation) []protocol.Invoker

cluster/loadbalance.go

@@ -22,7 +22,7 @@ import (
 )
 
 // LoadBalance
-//Extension - LoadBalance
+// Extension - LoadBalance
 type LoadBalance interface {
 	Select([]protocol.Invoker, protocol.Invocation) protocol.Invoker
 }

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,7 @@ import (
 )
 
 const (
-	// LeastActive ...
+	// LeastActive is used to set the load balance extension
 	LeastActive = "leastactive"
 )
 
@@ -39,7 +39,9 @@ func init() {
 type leastActiveLoadBalance struct {
 }
 
-// NewLeastActiveLoadBalance ...
+// NewLeastActiveLoadBalance returns a least active load balance.
+//
+// A random mechanism based on actives, actives means the number of a consumer's requests have been sent to provider but not yet got response.
 func NewLeastActiveLoadBalance() cluster.LoadBalance {
 	return &leastActiveLoadBalance{}
 }

cluster/loadbalance/random.go

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

cluster/loadbalance/round_robin.go

@@ -52,7 +52,9 @@ func init() {
 
 type roundRobinLoadBalance struct{}
 
-// NewRoundRobinLoadBalance ...
+// NewRoundRobinLoadBalance returns a 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)