Add ClusterMetadata documentation

2 files changed, 18 insertions, 0 deletions

diff --git a/kafka/client_async.py b/kafka/client_async.py
index 9e30e09..5824e7a 100644
--- a/kafka/client_async.py
+++ b/kafka/client_async.py
@@ -48,6 +48,10 @@ class KafkaClient(object):
 
     This class is not thread-safe!
 
+    Attributes:
+        cluster (:any:`ClusterMetadata`): Local cache of cluster metadata, retrived
+            via MetadataRequests during :meth:`.poll`.
+
     Keyword Arguments:
         bootstrap_servers: 'host[:port]' string (or list of 'host[:port]'
             strings) that the consumer should contact to bootstrap initial
diff --git a/kafka/cluster.py b/kafka/cluster.py
index 0a5c07f..d646fdf 100644
--- a/kafka/cluster.py
+++ b/kafka/cluster.py
@@ -16,6 +16,20 @@ log = logging.getLogger(__name__)
 
 
 class ClusterMetadata(object):
+    """
+    A class to manage kafka cluster metadata.
+
+    This class does not perform any IO. It simply updates internal state
+    given API responses (MetadataResponse, GroupCoordinatorResponse).
+
+    Keyword Arguments:
+        retry_backoff_ms (int): Milliseconds to backoff when retrying on
+            errors. Default: 100.
+        metadata_max_age_ms (int): The period of time in milliseconds after
+            which we force a refresh of metadata even if we haven't seen any
+            partition leadership changes to proactively discover any new
+            brokers or partitions. Default: 300000
+    """
     DEFAULT_CONFIG = {
         'retry_backoff_ms': 100,
         'metadata_max_age_ms': 300000,