protocol.rb in ruby-kafka-0.4.1

- old
+ new

@@ -1,6 +1,15 @@
 module Kafka
+
+  # The protocol layer of the library.
+  #
+  # The Kafka protocol (https://kafka.apache.org/protocol) defines a set of API
+  # requests, each with a well-known numeric API key, as well as a set of error
+  # codes with specific meanings.
+  #
+  # This module, and the classes contained in it, implement the client side of
+  # the protocol.
   module Protocol
     # The replica id of non-brokers is always -1.
     REPLICA_ID = -1
 
     PRODUCE_API = 0
@@ -14,10 +23,11 @@
     HEARTBEAT_API = 12
     LEAVE_GROUP_API = 13
     SYNC_GROUP_API = 14
     SASL_HANDSHAKE_API = 17
 
+    # A mapping from numeric API keys to symbolic API names.
     APIS = {
       PRODUCE_API => :produce,
       FETCH_API => :fetch,
       LIST_OFFSET_API => :list_offset,
       TOPIC_METADATA_API => :topic_metadata,
@@ -29,10 +39,11 @@
       LEAVE_GROUP_API => :leave_group,
       SYNC_GROUP_API => :sync_group,
       SASL_HANDSHAKE_API => :sasl_handshake,
     }
 
+    # A mapping from numeric error codes to exception classes.
     ERRORS = {
       -1 => UnknownError,
        1 => OffsetOutOfRange,
        2 => CorruptMessage,
        3 => UnknownTopicOrPartition,
@@ -70,19 +81,29 @@
       40 => InvalidConfig,
       41 => NotController,
       42 => InvalidRequest
     }
 
+    # Handles an error code by either doing nothing (if there was no error) or
+    # by raising an appropriate exception.
+    #
+    # @param error_code Integer
+    # @raise [ProtocolError]
+    # @return [nil]
     def self.handle_error(error_code)
       if error_code == 0
         # No errors, yay!
       elsif error = ERRORS[error_code]
         raise error
       else
         raise UnknownError, "Unknown error with code #{error_code}"
       end
     end
 
+    # Returns the symbolic name for an API key.
+    #
+    # @param api_key Integer
+    # @return [Symbol]
     def self.api_name(api_key)
       APIS.fetch(api_key, :unknown)
     end
   end
 end