feat: Add formatter annotations for SQL snippets

CONTRIBUTING.md

@@ -14,18 +14,18 @@ Please use [the mailing list](https://groups.google.com/group/mybatis-user) inst
 
 ## Improving documentation
 
-- Documentations are placed under [src/site](https://github.com/mybatis/mybatis-3/tree/master/src/site) directory in [the xdoc format](https://maven.apache.org/doxia/references/xdoc-format.html), so it is basically the same as creating a patch to contribute documentation changes. Please see the [Contributing code](CONTRIBUTING.md#contributing-code) section.
+- Documentation is located under the [src/site](https://github.com/mybatis/mybatis-3/tree/master/src/site) directory in [the xdoc format](https://maven.apache.org/doxia/references/xdoc-format.html); thus, contributing documentation changes is essentially similar to submitting a patch for code changes. Please refer to the [Contributing code](CONTRIBUTING.md#contributing-code) section.
 
 ## Contributing code
 
 ### Formatting
 
-Mybatis-core is now being auto formatted.  Given nature of some code logic with mybatis, it is more appropriate to force a formatting structure manually for snippets such as sql statements.  To do so, add following blocks around code.
+MyBatis-core is now automatically formatted. Given the nature of some code logic in MyBatis, it is sometimes necessary to enforce a manual formatting structure for specific code snippets (e.g., SQL statements). To achieve this, enclose the code snippet with the following comments:
 
-- ```// @formatter:off``` to start the block of unformatted code
-- ```// @formatter:on``` to end the block of unformatted code
+// @formatter:off // 开始未格式化代码块
+// @formatter:on // 结束未格式化代码块
 
-If comment sections need same behaviour such as javadocs, note that the entire block must be around entire comment as direct usage does not properly indicate that formatter treats it all as one comment block regardless.
+If a comment block (such as Javadoc) requires the same behavior, ensure that the entire comment is enclosed within these markers; otherwise, the formatter may not correctly treat it as a single block.
 
 ### Copyright and License
 

README.md

@@ -1,5 +1,4 @@
-MyBatis SQL Mapper Framework for Java
-=====================================
+# MyBatis SQL Mapper Framework for Java
 
 [![build](https://github.com/mybatis/mybatis-3/actions/workflows/ci.yaml/badge.svg)](https://github.com/mybatis/mybatis-3/actions?query=workflow%3A%22Java+CI%22)
 [![Coverage Status](https://coveralls.io/repos/mybatis/mybatis-3/badge.svg?branch=master&service=github)](https://coveralls.io/github/mybatis/mybatis-3?branch=master)
@@ -16,53 +15,48 @@ The MyBatis SQL mapper framework makes it easier to use a relational database wi
 MyBatis couples objects with stored procedures or SQL statements using an XML descriptor or annotations.
 Simplicity is the biggest advantage of the MyBatis data mapper over object relational mapping tools.
 
-Essentials
-----------
+## Essentials
 
-* [See the docs](https://mybatis.org/mybatis-3)
-* [Download Latest](https://github.com/mybatis/mybatis-3/releases)
-* [Download Snapshot](https://oss.sonatype.org/content/repositories/snapshots/org/mybatis/mybatis/)
+- [See the docs](https://mybatis.org/mybatis-3)
+- [Download Latest](https://github.com/mybatis/mybatis-3/releases)
+- [Download Snapshot](https://oss.sonatype.org/content/repositories/snapshots/org/mybatis/mybatis/)
 
-Contributions
--------------
+## Contributions
 
 See [here](CONTRIBUTING.md)
 
-Tests
------
+## Tests
 
-Mybatis-3 code runs more expressive testing depending on jdk usage and platform.
+MyBatis-3 executes an extensive test suite based on the JDK version and operating system.
 
-By default, we set ```<excludedGroups>TestcontainersTests,RequireIllegalAccess</excludedGroups>``` which will exclude a subset of tests with @Tag('TestcontainersTests') and @Tag('RequireIllegalAccess').
+By default, we set `<excludedGroups>TestcontainersTests,RequireIllegalAccess</excludedGroups>` which will exclude a subset of tests with @Tag('TestcontainersTests') and @Tag('RequireIllegalAccess').
 
-When we run on ci platform, we further make adjustments as needed.  See [here](.github/workflows/ci.yaml) for details.
+When running on the CI platform, further adjustments are applied as needed. See [here](.github/workflows/ci.yaml) for details.
 
-As of 12/28/2024, using combined system + jdk will result in given number of tests ran.  This will change as tests are added or removed over time.
+As of December 28, 2024, running the combined system tests with various JDK versions results in the following test counts (these numbers may change over time):
 
-without adjusting settings (ie use as is, platform does not matter)
+**Using default settings (platform does not affect the count):**
 
-- any OS + jdk 17 = 1899 tests
-- any OS + jdk 21 = 1899 tests
-- any OS + jdk 23 = 1899 tests
-- any OS + jdk 24 = 1899 tests
-- any OS + jdk 25 = 1899 tests
+- Any OS + JDK 17: 1899 tests
+- Any OS + JDK 21: 1899 tests
+- Any OS + JDK 23: 1899 tests
+- Any OS + JDK 24: 1899 tests
+- Any OS + JDK 25: 1899 tests
 
-our adjustments for GH actions where platform does matter
+**For GitHub Actions (platform differences are considered):**
 
-- windows + jdk 17 = 1899 tests
-- windows + jdk 21 = 1899 tests
-- windows + jdk 23 = 1899 tests
-- windows + jdk 24 = 1899 tests
-- windows + jdk 25 = 1899 tests
-
-- linux + jdk 17 = 1934 tests
-- linux + jdk 21 = 1934 tests
-- linux + jdk 23 = 1934 tests
-- linux + jdk 24 = 1934 tests
-- linux + jdk 25 = 1934 tests
-
-- mac + jdk 17 = 1899 tests
-- mac + jdk 21 = 1899 tests
-- mac + jdk 23 = 1899 tests
-- mac + jdk 24 = 1899 tests
-- mac + jdk 25 = 1899 tests
+- Windows + JDK 17: 1899 tests
+- Windows + JDK 21: 1899 tests
+- Windows + JDK 23: 1899 tests
+- Windows + JDK 24: 1899 tests
+- Windows + JDK 25: 1899 tests
+- Linux + JDK 17: 1934 tests
+- Linux + JDK 21: 1934 tests
+- Linux + JDK 23: 1934 tests
+- Linux + JDK 24: 1934 tests
+- Linux + JDK 25: 1934 tests
+- Mac + JDK 17: 1899 tests
+- Mac + JDK 21: 1899 tests
+- Mac + JDK 23: 1899 tests
+- Mac + JDK 24: 1899 tests
+- Mac + JDK 25: 1899 tests

src/test/java/org/apache/ibatis/type/BlobInputStreamTypeHandlerTest.java

@@ -150,10 +150,14 @@ void integrationTest() throws IOException {
   }
 
   interface Mapper {
+    // @formatter:off
     @Select("SELECT ID, CONTENT FROM TEST_BLOB WHERE ID = #{id}")
+    // @formatter:on
     BlobContent findOne(int id);
 
+    // @formatter:off
     @Insert("INSERT INTO TEST_BLOB (ID, CONTENT) VALUES(#{id}, #{content})")
+    // @formatter:on
     void insert(BlobContent blobContent);
   }
 

src/test/java/org/apache/ibatis/type/ClobReaderTypeHandlerTest.java

@@ -148,7 +148,9 @@ void integrationTest() throws IOException {
   }
 
   interface Mapper {
+    // @formatter:off
     @Select("SELECT ID, CONTENT FROM TEST_CLOB WHERE ID = #{id}")
+    // @formatter:on
     ClobContent findOne(int id);
 
     @Insert("INSERT INTO TEST_CLOB (ID, CONTENT) VALUES(#{id}, #{content})")