doc: add JavaDoc and inline comments for simple test (#260)

Author: nx-xn2002

fastexcel-core/src/main/java/cn/idev/excel/read/processor/DefaultAnalysisEventProcessor.java

@@ -117,8 +117,10 @@ private void dealData(AnalysisContext analysisContext) {
         for (ReadListener readListener : analysisContext.currentReadHolder().readListenerList()) {
             try {
                 if (isData) {
+                    // handle data row
                     readListener.invoke(readRowHolder.getCurrentRowAnalysisResult(), analysisContext);
                 } else {
+                    // handle data header
                     readListener.invokeHead(cellDataMap, analysisContext);
                 }
             } catch (Exception e) {

fastexcel-test/src/test/java/cn/idev/excel/test/core/simple/SimpleData.java

@@ -7,6 +7,11 @@
 import lombok.Setter;
 
 /**
+ * mock data format for simple read/write
+ * <p>
+ * Use ExcelProperty {@link ExcelProperty} to mark headers
+ * </p>
+ *
  * @author Jiaju Zhuang
  */
 @Getter

fastexcel-test/src/test/java/cn/idev/excel/test/core/simple/SimpleDataListener.java

@@ -4,34 +4,59 @@
 import java.util.List;
 import java.util.Map;
 
-import cn.idev.excel.event.AnalysisEventListener;
 import cn.idev.excel.context.AnalysisContext;
-import com.alibaba.fastjson2.JSON;
+import cn.idev.excel.event.AnalysisEventListener;
+import cn.idev.excel.event.SyncReadListener;
 
+import com.alibaba.fastjson2.JSON;
 import org.junit.jupiter.api.Assertions;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
+ * Define an AnalysisEventListener to handler the Analysis event
+ *
  * @author Jiaju Zhuang
  */
 public class SimpleDataListener extends AnalysisEventListener<SimpleData> {
     private static final Logger LOGGER = LoggerFactory.getLogger(SimpleDataListener.class);
     List<SimpleData> list = new ArrayList<SimpleData>();
 
+    /**
+     * handle header of the file data
+     *
+     * @param headMap head map
+     * @param context context
+     */
     @Override
     public void invokeHeadMap(Map<Integer, String> headMap, AnalysisContext context) {
         LOGGER.debug("Head is:{}", JSON.toJSONString(headMap));
         Assertions.assertEquals(headMap.get(0), "姓名");
     }
 
+    /**
+     * handle data row in the file
+     * <p>
+     * this is the same way of implement as {@link SyncReadListener#invoke}
+     * all the data are stored synchronously
+     * </p>
+     *
+     * @param data    data
+     * @param context context
+     */
     @Override
     public void invoke(SimpleData data, AnalysisContext context) {
         list.add(data);
     }
 
+    /**
+     * do after all analyse process
+     *
+     * @param context context
+     */
     @Override
     public void doAfterAllAnalysed(AnalysisContext context) {
+        //check the results
         Assertions.assertEquals(list.size(), 10);
         Assertions.assertEquals(list.get(0).getName(), "姓名0");
         Assertions.assertEquals((int)(context.readSheetHolder().getSheetNo()), 0);

fastexcel-test/src/test/java/cn/idev/excel/test/core/simple/SimpleDataTest.java

@@ -7,10 +7,10 @@
 import java.util.List;
 import java.util.Map;
 
-import cn.idev.excel.read.listener.PageReadListener;
-import cn.idev.excel.test.util.TestFileUtil;
 import cn.idev.excel.EasyExcel;
+import cn.idev.excel.read.listener.PageReadListener;
 import cn.idev.excel.support.ExcelTypeEnum;
+import cn.idev.excel.test.util.TestFileUtil;
 
 import lombok.extern.slf4j.Slf4j;
 import org.junit.jupiter.api.Assertions;
@@ -20,6 +20,15 @@
 import org.junit.jupiter.api.TestMethodOrder;
 
 /**
+ * Test simple read/write for Excel formats:
+ * <li>Excel 2007 format (.xlsx)</li>
+ * <li>Excel 2003 format (.xls)</li>
+ * <li>CSV format (.csv)</li>
+ * Test methods are grouped by prefixes:
+ * <li>t0x: Basic read/write tests</li>
+ * <li>t1x: Synchronous reading tests</li>
+ * <li>t2x: Specific feature tests (sheet name reading, pagination, etc.)</li>
+ *
  * @author Jiaju Zhuang
  */
 @TestMethodOrder(MethodOrderer.MethodName.class)
@@ -52,8 +61,14 @@ public void t03ReadAndWriteCsv() {
         readAndWrite(fileCsv);
     }
 
+    /**
+     * Test simple read/write with file
+     *
+     * @param file file
+     */
     private void readAndWrite(File file) {
         EasyExcel.write(file, SimpleData.class).sheet().doWrite(data());
+        //use a SimpleDataListener object to handle and check result
         EasyExcel.read(file, SimpleData.class, new SimpleDataListener()).sheet().doRead();
     }
 
@@ -72,44 +87,96 @@ public void t06ReadAndWriteCsv() throws Exception {
         readAndWriteInputStream(fileCsv, ExcelTypeEnum.CSV);
     }
 
+    /**
+     * Test simple read/write with InputStream/OutputStream
+     *
+     * @param file          file used to generate InputStream/OutputStream
+     * @param excelTypeEnum excel type enum
+     * @throws Exception exception
+     */
     private void readAndWriteInputStream(File file, ExcelTypeEnum excelTypeEnum) throws Exception {
         EasyExcel.write(new FileOutputStream(file), SimpleData.class).excelType(excelTypeEnum).sheet().doWrite(data());
+        //use a SimpleDataListener object to handle and check result
         EasyExcel.read(new FileInputStream(file), SimpleData.class, new SimpleDataListener()).sheet().doRead();
     }
 
+    /**
+     * Test synchronous reading of Excel 2007 format
+     */
     @Test
     public void t11SynchronousRead07() {
         synchronousRead(file07);
     }
 
+    /**
+     * Test synchronous reading of Excel 2003 format
+     */
     @Test
     public void t12SynchronousRead03() {
         synchronousRead(file03);
     }
 
+    /**
+     * Test synchronous reading of CSV format
+     */
     @Test
     public void t13SynchronousReadCsv() {
         synchronousRead(fileCsv);
     }
 
+    /**
+     * test read sheet in an Excel file with specified sheetName
+     */
     @Test
     public void t21SheetNameRead07() {
         List<Map<Integer, Object>> list = EasyExcel.read(
                 TestFileUtil.readFile("simple" + File.separator + "simple07.xlsx"))
+            //set the sheet name to read
             .sheet("simple")
             .doReadSync();
         Assertions.assertEquals(1, list.size());
     }
 
+    /**
+     * test read sheet in an Excel file with specified sheetNo
+     */
+    @Test
+    public void t22SheetNoRead07() {
+        List<Map<Integer, Object>> list = EasyExcel.read(
+                TestFileUtil.readFile("simple" + File.separator + "simple07.xlsx"))
+            // sheetNo begin with 0
+            .sheet(1)
+            .doReadSync();
+        Assertions.assertEquals(1, list.size());
+    }
+
+    /**
+     * Test page reading with PageReadListener
+     * <p>
+     * PageReadListener processes Excel data in batches, triggering callbacks when reaching
+     * specified batch size. {@link PageReadListener#invoke}
+     * Useful for large files to prevent memory overflow
+     * </p>
+     */
     @Test
-    public void t22PageReadListener07() {
+    public void t23PageReadListener07() {
+        //Read the first 5 rows of an Excel file
         EasyExcel.read(file07, SimpleData.class,
                 new PageReadListener<SimpleData>(dataList -> {
                     Assertions.assertEquals(5, dataList.size());
                 }, 5))
             .sheet().doRead();
     }
 
+    /**
+     * Synchronous reading of Excel files
+     * <p>
+     * Unlike asynchronous reading with listeners, synchronous reading loads all data into memory
+     * and returns a complete data list. It may cause memory issues when processing large files.
+     * </p>
+     *
+     * @param file file
+     */
     private void synchronousRead(File file) {
         // Synchronous read file
         List<Object> list = EasyExcel.read(file).head(SimpleData.class).sheet().doReadSync();
@@ -118,6 +185,11 @@ private void synchronousRead(File file) {
         Assertions.assertEquals(((SimpleData)list.get(0)).getName(), "姓名0");
     }
 
+    /**
+     * mock data
+     *
+     * @return {@link List }<{@link SimpleData }>
+     */
     private List<SimpleData> data() {
         List<SimpleData> list = new ArrayList<SimpleData>();
         for (int i = 0; i < 10; i++) {