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.