docs: clarify Balancer is equivalent to Java's PartitionAssignor

pkg/kgo/config.go

@@ -1178,16 +1178,15 @@ func ConsumerGroup(group string) GroupOpt {
 }
 
 // Balancers sets the group balancers to use for dividing topic partitions
-// among group members, overriding the defaults.
-//
-// The current default is [cooperative-sticky].
+// among group members, overriding the current default [cooperative-sticky].
+// This option is equivalent to Kafka's partition.assignment.strategies option.
 //
 // For balancing, Kafka chooses the first protocol that all group members agree
 // to support.
 //
-// Note that if you want to opt in to cooperative-sticky rebalancing,
-// cooperative group balancing is incompatible with eager (classical)
-// rebalancing and requires a careful rollout strategy (see KIP-429).
+// Note that if you opt in to cooperative-sticky rebalancing, cooperative group
+// balancing is incompatible with eager (classical) rebalancing and requires a
+// careful rollout strategy (see KIP-429).
 func Balancers(balancers ...GroupBalancer) GroupOpt {
 	return groupOpt{func(cfg *cfg) { cfg.balancers = balancers }}
 }

pkg/kgo/group_balancer.go

@@ -12,6 +12,8 @@ import (
 )
 
 // GroupBalancer balances topics and partitions among group members.
+//
+// A GroupBalancer is roughly equivalent to Kafka's PartitionAssignor.
 type GroupBalancer interface {
 	// ProtocolName returns the name of the protocol, e.g. roundrobin,
 	// range, sticky.
@@ -135,6 +137,10 @@ func (b *ConsumerBalancer) NewPlan() *BalancePlan {
 
 // ConsumerBalancerBalance is what the ConsumerBalancer invokes to balance a
 // group.
+//
+// This is a complicated interface, but in short, this interface has one
+// function that implements the actual balancing logic: using the input
+// balancer, balance the input topics and partitions.
 type ConsumerBalancerBalance interface {
 	Balance(*ConsumerBalancer, map[string]int32) IntoSyncAssignment
 }