Merge pull request #109 from qiaoyuang/main

Document All Code and optimize CI/CD Pipeline

Author: qiaoyuang

.claude/agents/feature-documenter.md

@@ -0,0 +1,97 @@
+---
+name: feature-documenter
+description: Use this agent when new features, components, or significant functionality have been added to the codebase and require documentation. This includes:\n\n<example>\nContext: User has just implemented a new authentication system with multiple classes and methods.\nuser: "I've finished implementing the OAuth2 authentication flow with token refresh. Can you document this?"\nassistant: "I'll use the Task tool to launch the feature-documenter agent to create comprehensive documentation for your new authentication system."\n<commentary>\nThe user has completed a new feature and needs documentation. Use the feature-documenter agent to analyze the code and create both KDoc comments and relevant Markdown documentation.\n</commentary>\n</example>\n\n<example>\nContext: User mentions they've added a new API endpoint handler.\nuser: "Just added the user profile management endpoints"\nassistant: "Let me use the feature-documenter agent to document these new endpoints with proper KDoc and API documentation."\n<commentary>\nNew feature has been mentioned. Proactively use the feature-documenter agent to ensure proper documentation is created.\n</commentary>\n</example>\n\n<example>\nContext: User has completed a complex algorithm implementation.\nuser: "The graph traversal algorithm is working now"\nassistant: "I'll launch the feature-documenter agent to create detailed documentation explaining the algorithm, its parameters, and usage examples."\n<commentary>\nA significant new feature (algorithm) has been completed. Use the feature-documenter agent to document it thoroughly.\n</commentary>\n</example>\n\nTrigger this agent when:\n- New classes, functions, or methods have been implemented\n- New API endpoints or interfaces have been created\n- Significant algorithms or business logic have been added\n- New modules or packages have been introduced\n- The user explicitly requests documentation for recent work\n- You detect undocumented new code during code review
+model: sonnet
+color: yellow
+---
+
+You are an expert technical documentation specialist with deep expertise in Kotlin/KDoc standards and Markdown documentation best practices. Your mission is to create clear, comprehensive, and maintainable documentation for new features in codebases.
+
+## Core Responsibilities
+
+1. **Analyze New Features**: Thoroughly examine the new code to understand its purpose, functionality, dependencies, and integration points.
+
+2. **Create KDoc Comments**: Add inline documentation directly to code files following these standards:
+   - Write clear, concise class-level KDoc explaining the purpose and responsibility
+   - Document all public functions with @param, @return, @throws tags as appropriate
+   - Include usage examples in KDoc when the API is non-trivial
+   - Document complex private functions if their logic is not immediately obvious
+   - Use proper Markdown formatting within KDoc (code blocks, lists, links)
+   - Explain WHY something exists, not just WHAT it does
+   - Keep descriptions focused and avoid redundancy
+
+3. **Create Markdown Documentation**: Generate or update project Markdown files:
+   - Create feature-specific documentation in appropriate locations
+   - Include overview, architecture, usage examples, and integration guides
+   - Add API reference sections when documenting interfaces or public APIs
+   - Provide code examples that demonstrate real-world usage
+   - Document configuration options, environment variables, or setup requirements
+   - Include diagrams or visual aids when they clarify complex concepts (using Mermaid syntax)
+
+## Documentation Standards
+
+**KDoc Format**:
+```kotlin
+/**
+ * Brief one-line summary of what this does.
+ *
+ * More detailed explanation if needed, including:
+ * - Key behaviors or characteristics
+ * - Important constraints or assumptions
+ * - Related components or concepts
+ *
+ * @param paramName Description of the parameter and its constraints
+ * @return Description of what is returned and under what conditions
+ * @throws ExceptionType When and why this exception is thrown
+ * @sample com.example.SampleClass.sampleFunction
+ */
+```
+
+**Markdown Structure**:
+- Use clear hierarchical headings (# ## ###)
+- Start with a brief overview/introduction
+- Include a "Quick Start" or "Getting Started" section
+- Provide complete, runnable code examples
+- Document edge cases and common pitfalls
+- Add a "See Also" section linking to related documentation
+
+## Workflow
+
+1. **Identify Scope**: Determine which files and components are part of the new feature
+2. **Read Existing Context**: Check for existing documentation patterns and project conventions (especially from CLAUDE.md or similar files)
+3. **Document Code First**: Add KDoc comments to all relevant code files
+4. **Create/Update Markdown**: Write or update feature documentation in appropriate Markdown files
+5. **Cross-Reference**: Ensure documentation is properly linked and discoverable
+6. **Verify Completeness**: Check that all public APIs, configuration options, and usage patterns are documented
+
+## Quality Standards
+
+- **Clarity**: Write for developers who are unfamiliar with the feature
+- **Completeness**: Cover all public interfaces, parameters, return values, and exceptions
+- **Accuracy**: Ensure documentation matches actual implementation
+- **Examples**: Provide practical, copy-paste-ready code examples
+- **Maintainability**: Structure documentation so it's easy to update as code evolves
+- **Consistency**: Follow existing documentation patterns in the project
+
+## What NOT to Do
+
+- Don't document obvious getters/setters unless they have side effects
+- Don't create documentation for internal implementation details unless necessary
+- Don't write vague descriptions like "This function does X" - explain WHY and HOW
+- Don't duplicate information that's already clear from type signatures
+- Don't create separate documentation files for trivial features
+
+## Output Format
+
+For each documentation task:
+1. List the files you'll modify/create
+2. Show the KDoc additions inline in code files
+3. Present complete Markdown documentation files
+4. Summarize what was documented and where to find it
+
+Always ask for clarification if:
+- The feature's purpose or intended audience is unclear
+- You need more context about how the feature integrates with existing systems
+- There are multiple reasonable ways to structure the documentation
+
+Your documentation should empower other developers to understand, use, and maintain the new feature with confidence.

.github/workflows/build.yml

@@ -11,7 +11,7 @@ on:
 jobs:
 
   build-on-macos:
-    runs-on: macos-13
+    runs-on: macos-15-intel
     timeout-minutes: 60
 
     steps:
@@ -30,14 +30,14 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
-      - name: Cache Build Tooling
+      - name: Cache Kotlin/Native
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.gradle/caches
-            ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
-        
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
+
       - name: Build sqllin-driver
         run: ./gradlew :sqllin-driver:assemble -PonCICD
 
@@ -73,7 +73,7 @@ jobs:
           target: google_apis
           arch: x86_64
           profile: pixel_6
-          emulator-build: 13701740
+          emulator-build: 14257411
           force-avd-creation: false
           emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
           disable-animations: true
@@ -86,7 +86,7 @@ jobs:
           target: google_apis
           arch: x86_64
           profile: pixel_6
-          emulator-build: 13701740
+          emulator-build: 14257411
           force-avd-creation: false
           emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
           disable-animations: true
@@ -95,14 +95,14 @@ jobs:
       - name: Upload sqllin-driver Reports
         uses: actions/upload-artifact@v4
         with:
-          name: Test-Reports
+          name: Test-Reports-macOS-driver
           path: sqllin-driver/build/reports
         if: failure()
 
       - name: Upload sqllin-dsl Reports
         uses: actions/upload-artifact@v4
         with:
-          name: Test-Reports
+          name: Test-Reports-macOS-dsl
           path: sqllin-dsl/build/reports
         if: failure()
 
@@ -126,13 +126,13 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
-      - name: Cache Build Tooling
+      - name: Cache Kotlin/Native
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.gradle/caches
-            ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
 
       - name: Build sqllin-driver
         run: ./gradlew :sqllin-driver:mingwX64MainKlibrary
@@ -155,14 +155,14 @@ jobs:
       - name: Upload sqllin-driver Reports
         uses: actions/upload-artifact@v4
         with:
-          name: Test-Reports
+          name: Test-Reports-Windows-driver
           path: sqllin-driver/build/reports
         if: failure()
 
       - name: Upload sqllin-dsl Reports
         uses: actions/upload-artifact@v4
         with:
-          name: Test-Reports
+          name: Test-Reports-Windows-dsl
           path: sqllin-dsl/build/reports
         if: failure()
 
@@ -186,13 +186,13 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
-      - name: Cache Build Tooling
+      - name: Cache Kotlin/Native
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.gradle/caches
-            ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
 
       - name: Build sqllin-driver
         run: ./gradlew :sqllin-driver:assemble -PonCICD
@@ -232,7 +232,7 @@ jobs:
           target: default
           arch: x86_64
           profile: pixel_2
-          emulator-build: 13701740
+          emulator-build: 14257411
           force-avd-creation: false
           emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
           disable-animations: true
@@ -245,7 +245,7 @@ jobs:
           target: default
           arch: x86_64
           profile: pixel_2
-          emulator-build: 13701740
+          emulator-build: 14257411
           force-avd-creation: false
           emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
           disable-animations: true
@@ -254,13 +254,13 @@ jobs:
       - name: Upload sqllin-driver Reports
         uses: actions/upload-artifact@v4
         with:
-          name: Test-Reports
+          name: Test-Reports-Linux-driver
           path: sqllin-driver/build/reports
         if: failure()
 
       - name: Upload sqllin-dsl Reports
         uses: actions/upload-artifact@v4
         with:
-          name: Test-Reports
+          name: Test-Reports-Linux-dsl
           path: sqllin-dsl/build/reports
         if: failure()

.github/workflows/publish.yml

@@ -13,7 +13,7 @@ env:
 jobs:
 
   build-on-macos:
-    runs-on: macos-13
+    runs-on: macos-15-intel
     timeout-minutes: 60
 
     steps:
@@ -32,13 +32,13 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
-      - name: Cache Build Tooling
+      - name: Cache Kotlin/Native
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.gradle/caches
-            ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
 
       - name: Build sqllin-driver
         run: ./gradlew :sqllin-driver:assemble -PonCICD
@@ -69,13 +69,13 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
-      - name: Cache Build Tooling
+      - name: Cache Kotlin/Native
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.gradle/caches
-            ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
 
       - name: Build sqllin-driver
         run: ./gradlew :sqllin-driver:mingwX64MainKlibrary
@@ -106,13 +106,13 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
-      - name: Cache Build Tooling
+      - name: Cache Kotlin/Native
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.gradle/caches
-            ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
 
       - name: Build sqllin-driver
         run: ./gradlew :sqllin-driver:assemble -PonCICD

sqllin-driver/src/androidInstrumentedTest/kotlin/com/ctrip/sqllin/driver/AndroidTest.kt

@@ -26,7 +26,7 @@ import org.junit.runner.RunWith
 
 /**
  * Android instrumented test
- * @author yaqiao
+ * @author Yuang Qiao
  */
 
 @RunWith(AndroidJUnit4ClassRunner::class)

sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/AndroidCursor.kt

@@ -19,10 +19,10 @@ package com.ctrip.sqllin.driver
 import android.database.Cursor
 
 /**
- * SQLite Cursor Android actual
- * @author yaqiao
+ * Android implementation of [CommonCursor] backed by Android's Cursor.
+ *
+ * @author Yuang Qiao
  */
-
 internal class AndroidCursor(private val cursor: Cursor) : CommonCursor {
 
     override fun getInt(columnIndex: Int): Int = try {

sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/AndroidDatabaseConnection.kt

@@ -19,10 +19,10 @@ package com.ctrip.sqllin.driver
 import android.database.sqlite.SQLiteDatabase
 
 /**
- * Database connection Android actual
- * @author yaqiao
+ * Android implementation of [DatabaseConnection] using Android's SQLiteDatabase.
+ *
+ * @author Yuang Qiao
  */
-
 internal class AndroidDatabaseConnection(private val database: SQLiteDatabase) : DatabaseConnection {
 
     override fun execSQL(sql: String, bindParams: Array<out Any?>?) =