add comments for interfaces

Author: shuwenwei

iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/operator/process/copyto/CopyToOptions.java

@@ -30,19 +30,68 @@
 import java.util.List;
 import java.util.Set;
 
+/**
+ * Interface for COPY TO command options.
+ *
+ * <p>This interface defines the configuration for COPY TO operations, including target format,
+ * target table name, column mappings, and memory management. Implementations provide
+ * format-specific validation and inference logic.
+ */
 public interface CopyToOptions extends Accountable {
 
+  /**
+   * Infers and validates options based on query analysis and relation plan.
+   *
+   * <p>This method is called during analysis phase to fill in default values and validate
+   * user-specified options against the query structure. For example, it can infer the target time
+   * column from the query's time column if not explicitly specified.
+   *
+   * @param analysis the query analysis containing metadata about the query
+   * @param queryRelationPlan the logical relation plan of the inner query
+   * @param columnHeaders the column headers from the query result
+   */
   void infer(Analysis analysis, RelationPlan queryRelationPlan, List<ColumnHeader> columnHeaders);
 
+  /**
+   * Validates the options against the actual column schema.
+   *
+   * <p>This method is called after planning to ensure the specified options (e.g., target columns,
+   * tags) are valid for the given output schema.
+   *
+   * @param columnHeaders the column headers of the query result
+   * @throws SemanticException if validation fails
+   */
   void check(List<ColumnHeader> columnHeaders);
 
+  /**
+   * Returns the response column headers for the result set.
+   *
+   * <p>These headers describe the columns that will be returned to the client after the COPY TO
+   * operation completes (e.g., file path, row count).
+   *
+   * @return list of column headers for the response
+   */
   List<ColumnHeader> getRespColumnHeaders();
 
+  /**
+   * Returns the target output format.
+   *
+   * @return the format enum value
+   */
   Format getFormat();
 
+  /**
+   * Estimates the maximum memory usage in bytes required for writing.
+   *
+   * <p>This is used for memory management and determining whether to flush data to disk.
+   *
+   * @return estimated maximum memory usage in bytes
+   */
   long estimatedMaxRamBytesInWrite();
 
+  /** Supported output formats for COPY TO command. */
   enum Format {
+    /** TsFile format output. */
     TSFILE,
   }
 

iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/operator/process/copyto/IFormatCopyToWriter.java

@@ -23,12 +23,50 @@
 
 import java.io.IOException;
 
+/**
+ * Interface for writing query results to external storage formats.
+ *
+ * <p>This interface abstracts the writing logic so that different output formats (e.g., TsFile,
+ * CSV) can be supported. Each implementation handles format-specific operations like encoding,
+ * schema definition, and file sealing.
+ */
 public interface IFormatCopyToWriter {
+
+  /**
+   * Writes a TsBlock containing query results to the target storage.
+   *
+   * @param tsBlock the data block to write, containing rows of query results
+   * @throws Exception if write fails (e.g., IO error, encoding error)
+   */
   void write(TsBlock tsBlock) throws Exception;
 
+  /**
+   * Builds a TsBlock containing metadata or summary information about the written data.
+   *
+   * <p>This is typically called after all data has been written to return information about the
+   * output, such as file paths, row counts, or statistics.
+   *
+   * @return a TsBlock containing result metadata, or null if no result is needed
+   */
   TsBlock buildResultTsBlock();
 
+  /**
+   * Finalizes the writing process and prepares the file for reading.
+   *
+   * <p>This method ensures all data is flushed to disk and necessary footer/headers are written.
+   * After seal() is called, no more data should be written.
+   *
+   * @throws Exception if sealing fails
+   */
   void seal() throws Exception;
 
+  /**
+   * Closes the writer and releases all resources.
+   *
+   * <p>This method should be called after seal() to ensure proper cleanup of file handles, buffers,
+   * and other resources.
+   *
+   * @throws IOException if close fails
+   */
   void close() throws IOException;
 }