KAFKA-17864: add descriptions to fields in the agreement (#17681)

Improve descriptive information in Kafka protocol documentation. Reviewers: Mickael Maison <[email protected]>, Andrew Schofield <[email protected]>, Apoorv Mittal <[email protected]>
apache · Dec 7, 2024 · 38e727f · 38e727f
1 parent f2e1a4c
commit 38e727f
Show file tree

Hide file tree

Showing 104 changed files with 624 additions and 480 deletions.
diff --git a/clients/src/main/resources/common/message/AddPartitionsToTxnRequest.json b/clients/src/main/resources/common/message/AddPartitionsToTxnRequest.json
@@ -59,7 +59,7 @@
       { "name": "Name", "type": "string", "versions": "0+", "mapKey": true, "entityType": "topicName",
         "about": "The name of the topic." },
       { "name": "Partitions", "type": "[]int32", "versions": "0+",
-        "about": "The partition indexes to add to the transaction" }
+        "about": "The partition indexes to add to the transaction." }
     ]}
   ]
 }
diff --git a/clients/src/main/resources/common/message/AddPartitionsToTxnResponse.json b/clients/src/main/resources/common/message/AddPartitionsToTxnResponse.json
@@ -48,7 +48,7 @@
       { "name": "Name", "type": "string", "versions": "0+", "mapKey": true, "entityType": "topicName",
         "about": "The topic name." },
       { "name": "ResultsByPartition", "type": "[]AddPartitionsToTxnPartitionResult", "versions": "0+",
-        "about": "The results for each partition" }
+        "about": "The results for each partition." }
     ]},
     { "name": "AddPartitionsToTxnPartitionResult", "versions": "0+", "fields": [
       { "name": "PartitionIndex", "type": "int32", "versions": "0+", "mapKey": true,

diff --git a/clients/src/main/resources/common/message/AddRaftVoterRequest.json b/clients/src/main/resources/common/message/AddRaftVoterRequest.json
@@ -21,20 +21,22 @@
   "validVersions": "0",
   "flexibleVersions": "0+",
   "fields": [
-    { "name": "ClusterId", "type": "string", "versions": "0+", "nullableVersions": "0+" },
-    { "name": "TimeoutMs", "type": "int32", "versions": "0+" },
+    { "name": "ClusterId", "type": "string", "versions": "0+", "nullableVersions": "0+",
+      "about": "The cluster id." },
+    { "name": "TimeoutMs", "type": "int32", "versions": "0+",
+      "about": "The maximum time to wait for the request to complete before returning."},
     { "name": "VoterId", "type": "int32", "versions": "0+",
-      "about": "The replica id of the voter getting added to the topic partition" },
+      "about": "The replica id of the voter getting added to the topic partition." },
     { "name": "VoterDirectoryId", "type": "uuid", "versions": "0+",
-      "about": "The directory id of the voter getting added to the topic partition" },
+      "about": "The directory id of the voter getting added to the topic partition." },
     { "name": "Listeners", "type": "[]Listener", "versions": "0+",
-      "about": "The endpoints that can be used to communicate with the voter", "fields": [
+      "about": "The endpoints that can be used to communicate with the voter.", "fields": [
       { "name": "Name", "type": "string", "versions": "0+", "mapKey": true,
-        "about": "The name of the endpoint" },
+        "about": "The name of the endpoint." },
       { "name": "Host", "type": "string", "versions": "0+",
-        "about": "The hostname" },
+        "about": "The hostname." },
       { "name": "Port", "type": "uint16", "versions": "0+",
-        "about": "The port" }
+        "about": "The port." }
     ]}
   ]
 }
diff --git a/clients/src/main/resources/common/message/AddRaftVoterResponse.json b/clients/src/main/resources/common/message/AddRaftVoterResponse.json
@@ -23,7 +23,7 @@
     { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
       "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
     { "name": "ErrorCode", "type": "int16", "versions": "0+",
-      "about": "The error code, or 0 if there was no error" },
+      "about": "The error code, or 0 if there was no error." },
     { "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+", "ignorable": true,
       "about": "The error message, or null if there was no error." }
   ]

diff --git a/clients/src/main/resources/common/message/AllocateProducerIdsRequest.json b/clients/src/main/resources/common/message/AllocateProducerIdsRequest.json
@@ -22,8 +22,8 @@
   "flexibleVersions": "0+",
   "fields": [
     { "name": "BrokerId", "type": "int32", "versions": "0+", "entityType": "brokerId",
-      "about": "The ID of the requesting broker" },
+      "about": "The ID of the requesting broker." },
     { "name": "BrokerEpoch", "type": "int64", "versions": "0+", "default": "-1",
-      "about": "The epoch of the requesting broker" }
+      "about": "The epoch of the requesting broker." }
   ]
 }
diff --git a/clients/src/main/resources/common/message/AllocateProducerIdsResponse.json b/clients/src/main/resources/common/message/AllocateProducerIdsResponse.json
@@ -23,10 +23,10 @@
     { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
       "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
     { "name": "ErrorCode", "type": "int16", "versions": "0+",
-      "about": "The top level response error code" },
+      "about": "The top level response error code." },
     { "name": "ProducerIdStart", "type": "int64", "versions": "0+", "entityType": "producerId",
-      "about": "The first producer ID in this range, inclusive"},
+      "about": "The first producer ID in this range, inclusive."},
     { "name": "ProducerIdLen", "type": "int32", "versions": "0+",
-      "about": "The number of producer IDs in this range"}
+      "about": "The number of producer IDs in this range."}
   ]
 }
diff --git a/clients/src/main/resources/common/message/AlterPartitionReassignmentsResponse.json b/clients/src/main/resources/common/message/AlterPartitionReassignmentsResponse.json
@@ -29,9 +29,9 @@
     { "name": "Responses", "type": "[]ReassignableTopicResponse", "versions": "0+",
       "about": "The responses to topics to reassign.", "fields": [
       { "name": "Name", "type": "string", "versions": "0+", "entityType": "topicName",
-        "about": "The topic name" },
+        "about": "The topic name." },
       { "name": "Partitions", "type": "[]ReassignablePartitionResponse", "versions": "0+",
-        "about": "The responses to partitions to reassign", "fields": [
+        "about": "The responses to partitions to reassign.", "fields": [
         { "name": "PartitionIndex", "type": "int32", "versions": "0+",
           "about": "The partition index." },
         { "name": "ErrorCode", "type": "int16", "versions": "0+",

diff --git a/clients/src/main/resources/common/message/AlterPartitionRequest.json b/clients/src/main/resources/common/message/AlterPartitionRequest.json
@@ -27,22 +27,25 @@
   "flexibleVersions": "0+",
   "fields": [
     { "name": "BrokerId", "type": "int32", "versions": "0+", "entityType": "brokerId",
-      "about": "The ID of the requesting broker" },
+      "about": "The ID of the requesting broker." },
     { "name": "BrokerEpoch", "type": "int64", "versions": "0+", "default": "-1",
-      "about": "The epoch of the requesting broker" },
-    { "name": "Topics", "type": "[]TopicData", "versions": "0+", "fields": [
+      "about": "The epoch of the requesting broker." },
+    { "name": "Topics", "type": "[]TopicData", "versions": "0+",
+      "about": "The topics to alter ISRs for.", "fields": [
       { "name":  "TopicName", "type": "string", "versions": "0-1", "ignorable": true, "entityType": "topicName",
-        "about": "The name of the topic to alter ISRs for" },
+        "about": "The name of the topic to alter ISRs for." },
       { "name":  "TopicId", "type": "uuid", "versions": "2+", "ignorable": true,
-        "about": "The ID of the topic to alter ISRs for" },
-      { "name": "Partitions", "type": "[]PartitionData", "versions": "0+", "fields": [
+        "about": "The ID of the topic to alter ISRs for." },
+      { "name": "Partitions", "type": "[]PartitionData", "versions": "0+",
+        "about": "The partitions to alter ISRs for.", "fields": [
         { "name": "PartitionIndex", "type": "int32", "versions": "0+",
-          "about": "The partition index" },
+          "about": "The partition index." },
         { "name": "LeaderEpoch", "type": "int32", "versions": "0+",
-          "about": "The leader epoch of this partition" },
+          "about": "The leader epoch of this partition." },
         { "name": "NewIsr", "type": "[]int32", "versions": "0-2", "entityType": "brokerId",
           "about": "The ISR for this partition. Deprecated since version 3." },
-        { "name": "NewIsrWithEpochs", "type": "[]BrokerState", "versions": "3+", "fields": [
+        { "name": "NewIsrWithEpochs", "type": "[]BrokerState", "versions": "3+",
+          "about":  "The ISR for this partition.", "fields": [
           { "name": "BrokerId", "type": "int32", "versions": "3+", "entityType": "brokerId",
             "about": "The ID of the broker." },
           { "name": "BrokerEpoch", "type": "int64", "versions": "3+", "default": "-1",

diff --git a/clients/src/main/resources/common/message/AlterPartitionResponse.json b/clients/src/main/resources/common/message/AlterPartitionResponse.json
@@ -29,17 +29,19 @@
     { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
       "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
     { "name": "ErrorCode", "type": "int16", "versions": "0+",
-      "about": "The top level response error code" },
-    { "name": "Topics", "type": "[]TopicData", "versions": "0+", "fields": [
+      "about": "The top level response error code." },
+    { "name": "Topics", "type": "[]TopicData", "versions": "0+",
+      "about": "The responses for each topic.", "fields": [
       { "name": "TopicName", "type": "string", "versions": "0-1", "ignorable": true, "entityType": "topicName",
-        "about": "The name of the topic" },
+        "about": "The name of the topic." },
       { "name":  "TopicId", "type": "uuid", "versions": "2+", "ignorable": true,
-        "about": "The ID of the topic" },
-      { "name": "Partitions", "type": "[]PartitionData", "versions": "0+", "fields": [
+        "about": "The ID of the topic." },
+      { "name": "Partitions", "type": "[]PartitionData", "versions": "0+",
+        "about": "The responses for each partition.", "fields": [
         { "name": "PartitionIndex", "type": "int32", "versions": "0+",
-          "about": "The partition index" },
+          "about": "The partition index." },
         { "name": "ErrorCode", "type": "int16", "versions": "0+",
-          "about": "The partition level error code" },
+          "about": "The partition level error code." },
         { "name": "LeaderId", "type": "int32", "versions": "0+", "entityType": "brokerId",
           "about": "The broker ID of the leader." },
         { "name": "LeaderEpoch", "type": "int32", "versions": "0+",

diff --git a/clients/src/main/resources/common/message/ApiVersionsResponse.json b/clients/src/main/resources/common/message/ApiVersionsResponse.json
@@ -45,10 +45,10 @@
     ]},
     { "name": "ThrottleTimeMs", "type": "int32", "versions": "1+", "ignorable": true,
       "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
-    { "name":  "SupportedFeatures", "type": "[]SupportedFeatureKey", "ignorable": true,
-      "versions":  "3+", "tag": 0, "taggedVersions": "3+",
+    { "name": "SupportedFeatures", "type": "[]SupportedFeatureKey", "ignorable": true,
+      "versions": "3+", "tag": 0, "taggedVersions": "3+",
       "about": "Features supported by the broker. Note: in v0-v3, features with MinSupportedVersion = 0 are omitted.",
-      "fields":  [
+      "fields": [
         { "name": "Name", "type": "string", "versions": "3+", "mapKey": true,
           "about": "The name of the feature." },
         { "name": "MinVersion", "type": "int16", "versions": "3+",
@@ -59,21 +59,21 @@
     },
     { "name": "FinalizedFeaturesEpoch", "type": "int64", "versions": "3+",
       "tag": 1, "taggedVersions": "3+", "default": "-1", "ignorable": true,
-      "about": "The monotonically increasing epoch for the finalized features information. Valid values are >= 0. A value of -1 is special and represents unknown epoch."},
-    { "name":  "FinalizedFeatures", "type": "[]FinalizedFeatureKey", "ignorable": true,
-      "versions":  "3+", "tag": 2, "taggedVersions": "3+",
+      "about": "The monotonically increasing epoch for the finalized features information. Valid values are >= 0. A value of -1 is special and represents unknown epoch." },
+    { "name": "FinalizedFeatures", "type": "[]FinalizedFeatureKey", "ignorable": true,
+      "versions": "3+", "tag": 2, "taggedVersions": "3+",
       "about": "List of cluster-wide finalized features. The information is valid only if FinalizedFeaturesEpoch >= 0.",
-      "fields":  [
-        {"name": "Name", "type": "string", "versions":  "3+", "mapKey": true,
-          "about": "The name of the feature."},
-        {"name":  "MaxVersionLevel", "type": "int16", "versions":  "3+",
-          "about": "The cluster-wide finalized max version level for the feature."},
-        {"name":  "MinVersionLevel", "type": "int16", "versions":  "3+",
-          "about": "The cluster-wide finalized min version level for the feature."}
+      "fields": [
+        { "name": "Name", "type": "string", "versions":  "3+", "mapKey": true,
+          "about": "The name of the feature." },
+        { "name": "MaxVersionLevel", "type": "int16", "versions":  "3+",
+          "about": "The cluster-wide finalized max version level for the feature." },
+        { "name": "MinVersionLevel", "type": "int16", "versions":  "3+",
+          "about": "The cluster-wide finalized min version level for the feature." }
       ]
     },
-    { "name":  "ZkMigrationReady", "type": "bool", "versions": "3+", "taggedVersions": "3+",
+    { "name": "ZkMigrationReady", "type": "bool", "versions": "3+", "taggedVersions": "3+",
       "tag": 3, "ignorable": true, "default": "false",
-      "about": "Set by a KRaft controller if the required configurations for ZK migration are present" }
+      "about": "Set by a KRaft controller if the required configurations for ZK migration are present." }
   ]
 }
diff --git a/clients/src/main/resources/common/message/AssignReplicasToDirsRequest.json b/clients/src/main/resources/common/message/AssignReplicasToDirsRequest.json
@@ -22,17 +22,20 @@
   "flexibleVersions": "0+",
   "fields": [
     { "name": "BrokerId", "type": "int32", "versions": "0+", "entityType": "brokerId",
-      "about": "The ID of the requesting broker" },
+      "about": "The ID of the requesting broker." },
     { "name": "BrokerEpoch", "type": "int64", "versions": "0+", "default": "-1",
-      "about": "The epoch of the requesting broker" },
-    { "name": "Directories", "type":  "[]DirectoryData", "versions": "0+", "fields":  [
-      { "name":  "Id", "type": "uuid", "versions": "0+", "about": "The ID of the directory" },
-      { "name": "Topics", "type": "[]TopicData", "versions": "0+", "fields": [
-        { "name":  "TopicId", "type": "uuid", "versions": "0+",
-          "about": "The ID of the assigned topic" },
-        { "name": "Partitions", "type": "[]PartitionData", "versions": "0+", "fields": [
+      "about": "The epoch of the requesting broker." },
+    { "name": "Directories", "type":  "[]DirectoryData", "versions": "0+",
+      "about": "The directories to which replicas should be assigned.", "fields":  [
+      { "name": "Id", "type": "uuid", "versions": "0+", "about": "The ID of the directory." },
+      { "name": "Topics", "type": "[]TopicData", "versions": "0+",
+        "about": "The topics assigned to the directory.", "fields": [
+        { "name": "TopicId", "type": "uuid", "versions": "0+",
+          "about": "The ID of the assigned topic." },
+        { "name": "Partitions", "type": "[]PartitionData", "versions": "0+",
+          "about": "The partitions assigned to the directory.", "fields": [
           { "name": "PartitionIndex", "type": "int32", "versions": "0+",
-            "about": "The partition index" }
+            "about": "The partition index." }
         ]}
       ]}
     ]}

diff --git a/clients/src/main/resources/common/message/AssignReplicasToDirsResponse.json b/clients/src/main/resources/common/message/AssignReplicasToDirsResponse.json
@@ -23,17 +23,20 @@
     { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
       "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
     { "name": "ErrorCode", "type": "int16", "versions": "0+",
-      "about": "The top level response error code" },
-    { "name": "Directories", "type":  "[]DirectoryData", "versions": "0+", "fields":  [
-      { "name":  "Id", "type": "uuid", "versions": "0+", "about": "The ID of the directory" },
-      { "name": "Topics", "type": "[]TopicData", "versions": "0+", "fields": [
-        { "name":  "TopicId", "type": "uuid", "versions": "0+",
-          "about": "The ID of the assigned topic" },
-        { "name": "Partitions", "type": "[]PartitionData", "versions": "0+", "fields": [
+      "about": "The top level response error code." },
+    { "name": "Directories", "type":  "[]DirectoryData", "versions": "0+",
+      "about": "The list of directories and their assigned partitions.", "fields":  [
+      { "name": "Id", "type": "uuid", "versions": "0+", "about": "The ID of the directory." },
+      { "name": "Topics", "type": "[]TopicData", "versions": "0+",
+        "about": "The list of topics and their assigned partitions.", "fields": [
+        { "name": "TopicId", "type": "uuid", "versions": "0+",
+          "about": "The ID of the assigned topic." },
+        { "name": "Partitions", "type": "[]PartitionData", "versions": "0+",
+          "about": "The list of assigned partitions.", "fields": [
           { "name": "PartitionIndex", "type": "int32", "versions": "0+",
-            "about": "The partition index" },
+            "about": "The partition index." },
           { "name": "ErrorCode", "type": "int16", "versions": "0+",
-            "about": "The partition level error code" }
+            "about": "The partition level error code." }
         ]}
       ]}
     ]}

diff --git a/clients/src/main/resources/common/message/BeginQuorumEpochRequest.json b/clients/src/main/resources/common/message/BeginQuorumEpochRequest.json
@@ -23,32 +23,33 @@
   "flexibleVersions": "1+",
   "fields": [
     { "name": "ClusterId", "type": "string", "versions": "0+",
-      "nullableVersions": "0+", "default": "null"},
+      "nullableVersions": "0+", "default": "null",
+      "about": "The cluster id." },
     { "name": "VoterId", "type": "int32", "versions": "1+", "ignorable": true, "default": "-1", "entityType": "brokerId",
-      "about": "The replica id of the voter receiving the request" },
-    { "name": "Topics", "type": "[]TopicData",
-      "versions": "0+", "fields": [
+      "about": "The replica id of the voter receiving the request." },
+    { "name": "Topics", "type": "[]TopicData", "versions": "0+",
+      "about": "The topics.", "fields": [
         { "name": "TopicName", "type": "string", "versions": "0+", "entityType": "topicName",
-          "about": "The topic name" },
-        { "name": "Partitions", "type": "[]PartitionData",
-          "versions": "0+", "fields": [
+          "about": "The topic name." },
+        { "name": "Partitions", "type": "[]PartitionData", "versions": "0+",
+          "about": "The partitions.", "fields": [
             { "name": "PartitionIndex", "type": "int32", "versions": "0+",
-              "about": "The partition index" },
+              "about": "The partition index." },
             { "name": "VoterDirectoryId", "type": "uuid", "versions": "1+", "ignorable": true,
-              "about": "The directory id of the receiving replica" },
+              "about": "The directory id of the receiving replica." },
             { "name": "LeaderId", "type": "int32", "versions": "0+", "entityType": "brokerId",
-              "about": "The ID of the newly elected leader"},
+              "about": "The ID of the newly elected leader." },
             { "name": "LeaderEpoch", "type": "int32", "versions": "0+",
-              "about": "The epoch of the newly elected leader"}
+              "about": "The epoch of the newly elected leader." }
           ]
         }
       ]
     },
     { "name": "LeaderEndpoints", "type": "[]LeaderEndpoint", "versions": "1+", "ignorable": true,
-      "about": "Endpoints for the leader", "fields": [
-        { "name": "Name", "type": "string", "versions": "1+", "mapKey": true, "about": "The name of the endpoint" },
-        { "name": "Host", "type": "string", "versions": "1+", "about": "The node's hostname" },
-        { "name": "Port", "type": "uint16", "versions": "1+", "about": "The node's port" }
+      "about": "Endpoints for the leader.", "fields": [
+        { "name": "Name", "type": "string", "versions": "1+", "mapKey": true, "about": "The name of the endpoint." },
+        { "name": "Host", "type": "string", "versions": "1+", "about": "The node's hostname." },
+        { "name": "Port", "type": "uint16", "versions": "1+", "about": "The node's port." }
       ]
     }
   ]