Improve comments in ConfigNode and DataNode

[wangx0502]

Description

Improve the readability and accuracy of comments in ConfigNode and DataNode.

Changes

• Add class-level documentation for important ConfigNode and DataNode components.
• Clarify lifecycle, consensus, RPC, query execution, storage, WAL, compaction, and subscription behavior.
• Fix inaccurate, redundant, and grammatically incorrect comments.
• Correct Javadocs that did not match the actual implementation.
• Remove trailing whitespace and apply Spotless formatting.
• Keep the review documents out of the source commits.

Tests

• git diff --check origin/master
• mvn spotless:check -pl iotdb-core/confignode,iotdb-core/datanode -DskipTests

No functional behavior was intentionally changed.

[Copilot]

🟡 Changes recommended

Restore DataNode automatic RPC-buffer memory-control activation before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR improves ConfigNode and DataNode comments and Javadocs across lifecycle, storage, query, consensus, RPC, WAL, and subscription components.

Changes:

• Adds class-level and lifecycle documentation.
• Corrects terminology, grammar, and implementation descriptions.
• Applies formatting and removes trailing whitespace.
• Review identified an unintended DataNode startup behavior change.

File summaries

File	Summary
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/subscription/receiver/SubscriptionReceiverV1.java	Documents subscription request handling and state ownership.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/subscription/agent/SubscriptionAgent.java	Documents subscription agent responsibilities.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/StorageEngine.java	Clarifies readiness and region lifecycle. Nit (2 votes): capitalize the sentence beginning with if.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/wal/WALManager.java	Documents WAL allocation and lifecycle management.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/wal/recover/WALRecoverManager.java	Documents WAL recovery coordination.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/wal/buffer/WALBuffer.java	Clarifies buffer rotation and synchronization.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/memtable/TsFileProcessor.java	Documents flush and close lifecycle. Nit (1 vote): qualify the flushing statement for forced-close paths.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/DataRegion.java	Clarifies processor-close waiting behavior.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/compaction/schedule/CompactionTaskManager.java	Documents compaction worker management.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/compaction/schedule/CompactionScheduleTaskManager.java	Documents scheduling and repair coordination.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/service/DataNodeShutdownHook.java	Documents orderly shutdown sequencing.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/service/DataNode.java	Documents startup and shutdown. Critical (3 votes): restore automatic RPC-buffer memory-controller activation before prepareDataNode().
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/schemaengine/SchemaEngine.java	Documents schema lifecycle. Nit (2 votes): correct the documented resource-clearing order.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/statement/StatementVisitor.java	Documents visitor dispatch behavior.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/execution/QueryExecution.java	Clarifies query lifecycle and timeout behavior.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/Coordinator.java	Documents query coordination.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/schedule/DriverScheduler.java	Documents task scheduling and resource controls.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/fragment/FragmentInstanceManager.java	Documents fragment lifecycle management.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/exchange/MPPDataExchangeManager.java	Clarifies exchange event handling.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/protocol/thrift/impl/DataNodeInternalRPCServiceImpl.java	Documents internal RPC responsibilities.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/protocol/thrift/impl/ClientRPCServiceImpl.java	Documents client RPC responsibilities.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/consensus/statemachine/schemaregion/SchemaRegionStateMachine.java	Documents schema consensus lifecycle.
iotdb-core/datanode/src/main/java/org/apache/iotdb/db/consensus/statemachine/dataregion/DataRegionStateMachine.java	Documents data consensus and retry behavior. Nit (3 votes): document both selected retry statuses and the pipe-generated exception.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/service/ConfigNode.java	Documents ConfigNode startup and shutdown. Nit (1 vote): distinguish seed and non-seed RPC startup ordering.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/procedure/Procedure.java	Corrects procedure documentation and typos.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/persistence/schema/ConfigMTree.java	Clarifies in-memory schema management.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/partition/PartitionManager.java	Clarifies maintenance interval units.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/node/NodeManager.java	Clarifies AINode registration and leadership behavior.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/load/service/StatisticsService.java	Documents statistics scheduling.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/load/service/HeartbeatService.java	Clarifies heartbeat responsibilities.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/load/service/EventService.java	Documents event checking.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/ConfigManager.java	Documents control-plane management.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/ClusterManager.java	Documents cluster retry and connectivity behavior.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/consensus/request/ConfigPhysicalPlanVisitor.java	Documents plan dispatch.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/consensus/request/ConfigPhysicalPlan.java	Documents plan serialization and deserialization. Nits (1 vote each): scope the discriminator Javadoc correctly and accurately describe BufferUnderflowException behavior.

Review details

Suppressed comments (4)

iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/consensus/request/ConfigPhysicalPlan.java:172

• The base method is also inherited by ConfigPhysicalReadPlan, whose serializeImpl is intentionally empty, so this Javadoc incorrectly promises that every plan includes a type discriminator and payload. Describe the method as delegating to the implementation-specific serialization, or explicitly scope the discriminator claim to serializable write plans.

  /**
   * Serializes this plan, including its type discriminator and implementation-specific payload.
   *
   * @return a buffer positioned at the beginning of the serialized plan
   */

iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/consensus/request/ConfigPhysicalPlan.java:202

• buffer.getShort() can throw BufferUnderflowException for a truncated type header; it is not converted to IOException. The new @throws text therefore inaccurately says type-read failures use the checked exception—either wrap that underflow or narrow the tag to unrecognized types and payload-read failures.

     * @throws IOException if the encoded plan type or payload cannot be read

iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/service/ConfigNode.java:163

• The unconditional RPC-ordering statement does not match the non-seed startup path: active() deliberately calls setUpRPCService() before sendRegisterConfigNodeRequest() so the leader can schedule capacity expansion, and the local consensus group is only inspected later. Please distinguish the seed path (RPC last) from the non-seed path instead of documenting RPC startup as always occurring after all request-handling services are ready.

   * <p>The method must preserve the distinction between seed and non-seed ConfigNodes and must
   * start the RPC service only after the local services required to handle requests are ready.

iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/memtable/TsFileProcessor.java:135

• The final sentence is not true for forced-close paths: DataRegion.forceCloseAllWorkingTsFileProcessors() calls putMemTableBackAndClose(), which releases the working MemTable and closes the writer without flushing it. Please qualify this statement so the lifecycle documentation does not promise flushing where the implementation intentionally does not do so.

 * <p>The flush/query lock coordinates reads, asynchronous flush, synchronous close, deletion, and
 * resource publication. A processor is closed only after its pending MemTables have been flushed.

• Files reviewed: 35/35 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[CRZbulabula]

This contract is not true for every implementation. ConfigPhysicalReadPlan.serializeImpl() is deliberately a no-op, so serializeToByteBuffer() returns an empty buffer with neither a type discriminator nor a payload for read plans. Please qualify the Javadoc to say that it serializes whatever the concrete implementation emits, or explicitly document the read-plan exception.

[CRZbulabula]

A truncated buffer is not covered by this documented exception: buffer.getShort() throws the unchecked BufferUnderflowException when fewer than two bytes remain. Please either validate/wrap buffer underflow as IOException or document the unchecked failure instead of promising IOException whenever the encoded type or payload cannot be read.

[CRZbulabula]

This is not true for the initial non-seed path. That path intentionally calls setUpRPCService() before sendRegisterConfigNodeRequest() and before the node has joined a consensus group so that the leader can schedule expansion. Please document this exception instead of stating that RPC always starts only after the required local services are ready.

[CRZbulabula]

The probes do not all originate from this ConfigNode. This method sends the complete node list to every registered ConfigNode and DataNode, each recipient performs doConnectionTest(nodeLocations), and the leader aggregates those per-node results. Please describe this as a cluster-wide or all-to-all connectivity test coordinated by this ConfigNode.

[CRZbulabula]

This cleanup contract is stronger than the implementation. deactivate() deregisters services and ConfigManager.close() shuts down the region maintainer, procedure executor, and consensus, but consensus shutdown does not guarantee that ConfigRegionStateMachine.stopLeaderServices() runs; ConfigRegionStateMachine.stop() itself only notifies the pipe runtime. The shutdown is also not implemented as reverse dependency order. Please narrow this Javadoc to the actual best-effort deactivation followed by process exit, or implement the promised cleanup.