KAFKA-19209: Improve clarity and readability of index.interval.bytes description

Author: shmily7829

40/generated/topic_config.html

@@ -89,7 +89,7 @@ <h4><a id="flush.messages"></a><a id="topicconfigs_flush.messages" href="#topicc
 </li>
 <li>
 <h4><a id="flush.ms"></a><a id="topicconfigs_flush.ms" href="#topicconfigs_flush.ms">flush.ms</a></h4>
-<p>This setting allows specifying a time interval at which we will force an fsync of data written to the log. For example if this was set to 1000 we would fsync after 1000 ms had passed. In general we recommend you not set this and use replication for durability and allow the operating system's background flush capabilities as it is more efficient.</p>
+<p>This setting allows specifying a time interval at which we will force an fsync of data written to the log. For example if this was set to 1000 we would fsync after 1000 ms had passed. Note that this setting depends on the broker-level configuration <code>log.flush.scheduler.interval.ms</code>, which controls how frequently the flush check occurs. In general we recommend you not set this and use replication for durability and allow the operating system's background flush capabilities as it is more efficient.</p>
 <table><tbody>
 <tr><th>Type:</th><td>long</td></tr>
 <tr><th>Default:</th><td>9223372036854775807</td></tr>
@@ -111,12 +111,7 @@ <h4><a id="follower.replication.throttled.replicas"></a><a id="topicconfigs_foll
 </li>
 <li>
 <h4><a id="index.interval.bytes"></a><a id="topicconfigs_index.interval.bytes" href="#topicconfigs_index.interval.bytes">index.interval.bytes</a></h4>
-<p>This setting controls how frequently Kafka adds entries to its offset index and, conditionally, to its time index. After appending a batch of messages, if the total bytes written since the last index entry exceed this value, Kafka will:</p>
-<ul>
-<li>Add an entry to the offset index for the batch's last offset.</li>
-<li>Attempt to add an entry to the time index if the batch's maximum timestamp is greater than the last indexed timestamp.</li>
-</ul>
-<p>The default setting ensures that we index a message roughly every 4096 bytes. More frequent indexing allows reads to jump closer to the exact position in the log but results in larger index files. You probably don't need to change this.</p>
+<p>This setting controls how frequently Kafka adds entries to its offset index and, conditionally, to its time index. The default setting ensures that we index a message roughly every 4096 bytes. More frequent indexing allows reads to jump closer to the exact position in the log but results in larger index files. You probably don't need to change this.<p> Note: the time index will be inserted only when the timestamp is greater than the last indexed timestamp.</p></p>
 <table><tbody>
 <tr><th>Type:</th><td>int</td></tr>
 <tr><th>Default:</th><td>4096 (4 kibibytes)</td></tr>
@@ -171,7 +166,7 @@ <h4><a id="max.compaction.lag.ms"></a><a id="topicconfigs_max.compaction.lag.ms"
 </li>
 <li>
 <h4><a id="max.message.bytes"></a><a id="topicconfigs_max.message.bytes" href="#topicconfigs_max.message.bytes">max.message.bytes</a></h4>
-<p>The largest record batch size allowed by Kafka (after compression if compression is enabled). If this is increased and there are consumers older than 0.10.2, the consumers' fetch size must also be increased so that they can fetch record batches this large. In the latest message format version, records are always grouped into batches for efficiency. In previous message format versions, uncompressed records are not grouped into batches and this limit only applies to a single record in that case.</p>
+<p>The largest record batch size allowed by Kafka (after compression if compression is enabled).</p>
 <table><tbody>
 <tr><th>Type:</th><td>int</td></tr>
 <tr><th>Default:</th><td>1048588</td></tr>
@@ -281,7 +276,7 @@ <h4><a id="remote.log.delete.on.disable"></a><a id="topicconfigs_remote.log.dele
 </li>
 <li>
 <h4><a id="remote.storage.enable"></a><a id="topicconfigs_remote.storage.enable" href="#topicconfigs_remote.storage.enable">remote.storage.enable</a></h4>
-<p>To enable tiered storage for a topic, set this configuration as true. You can not disable this config once it is enabled. It will be provided in future versions.</p>
+<p>To enable tiered storage for a topic, set this configuration to true. To disable tiered storage for a topic that has it enabled, set this configuration to false. When disabling, you must also set <code>remote.log.delete.on.disable</code> to true.</p>
 <table><tbody>
 <tr><th>Type:</th><td>boolean</td></tr>
 <tr><th>Default:</th><td>false</td></tr>