Document all code and configure the feature-documenter subagent

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.

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?>?) =

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

@@ -24,12 +24,13 @@ import android.os.Build
 import androidx.annotation.RequiresApi
 
 /**
- * SQLite extension Android
- * @author yaqiao
+ * Converts an Android Context to a [DatabasePath].
  */
-
 public fun Context.toDatabasePath(): DatabasePath = AndroidDatabasePath(this)
 
+/**
+ * Android-specific [DatabasePath] implementation wrapping a Context.
+ */
 @JvmInline
 internal value class AndroidDatabasePath(val context: Context) : DatabasePath
 
@@ -53,6 +54,9 @@ public actual fun openDatabase(config: DatabaseConfiguration): DatabaseConnectio
     return connection
 }
 
+/**
+ * SQLiteOpenHelper for Android versions below P (API level 28).
+ */
 private class OldAndroidDBHelper(
     private val config: DatabaseConfiguration,
 ) : SQLiteOpenHelper((config.path as AndroidDatabasePath).context, config.name, null, config.version) {
@@ -64,6 +68,9 @@ private class OldAndroidDBHelper(
         config.upgrade(AndroidDatabaseConnection(db), oldVersion, newVersion)
 }
 
+/**
+ * SQLiteOpenHelper for Android P (API level 28) and above with OpenParams support.
+ */
 @RequiresApi(Build.VERSION_CODES.P)
 private class AndroidDBHelper(
     private val config: DatabaseConfiguration,
@@ -76,6 +83,9 @@ private class AndroidDBHelper(
         config.upgrade(AndroidDatabaseConnection(db), oldVersion, newVersion)
 }
 
+/**
+ * Converts [DatabaseConfiguration] to Android's OpenParams for API level 28+.
+ */
 @RequiresApi(Build.VERSION_CODES.P)
 @Suppress("DEPRECATION")
 private fun DatabaseConfiguration.toAndroidOpenParams(): OpenParams = OpenParams

sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/platform/UtilsAndroid.kt

@@ -17,9 +17,7 @@
 package com.ctrip.sqllin.driver.platform
 
 /**
- * The tools with Android implementation
- * @author yaqiao
+ * Android file path separator (forward slash).
  */
-
 internal actual inline val separatorChar: Char
     get() = '/'

sqllin-driver/src/appleMain/kotlin/com/ctrip/sqllin/driver/platform/Lock.kt

@@ -19,11 +19,10 @@ package com.ctrip.sqllin.driver.platform
 import platform.Foundation.NSRecursiveLock
 
 /**
- * A simple lock implementation in Apple platforms.
- * Implementations of this class should be re-entrant.
- * @author yaqiao
+ * Apple platform lock implementation using NSRecursiveLock.
+ *
+ * @author Yuang Qiao
  */
-
 internal actual class Lock actual constructor() {
 
     private val nsRecursiveLock = NSRecursiveLock()

sqllin-driver/src/appleMain/kotlin/com/ctrip/sqllin/driver/platform/UtilsApple.kt

@@ -24,12 +24,13 @@ import platform.Foundation.NSString
 import platform.Foundation.create
 
 /**
- * The tools with Apple platforms implementation
- * @author yaqiao
+ * Converts C byte pointer to String using NSString on Apple platforms.
  */
-
 @OptIn(ExperimentalForeignApi::class, BetaInteropApi::class)
 internal actual fun bytesToString(bv: CPointer<ByteVar>): String = NSString.create(uTF8String = bv).toString()
 
+/**
+ * Apple platform file path separator (forward slash).
+ */
 internal actual inline val separatorChar: Char
     get() = '/'

sqllin-driver/src/appleTest/kotlin/com/ctrip/sqllin/driver/PlatformApple.kt

@@ -23,7 +23,7 @@ import platform.Foundation.NSUserDomainMask
 
 /**
  * Apple platform-related functions
- * @author yaqiao
+ * @author Yuang Qiao
  */
 
 @OptIn(UnsafeNumber::class)

sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/CommonCursor.kt

@@ -17,26 +17,70 @@
 package com.ctrip.sqllin.driver
 
 /**
- * SQLite Cursor common abstract
+ * Platform-agnostic interface for iterating over query results.
+ *
+ * Provides methods to access column data by index and navigate through result rows.
+ *
  * @author Yuang Qiao
  */
-
 public interface CommonCursor : AutoCloseable {
 
+    /**
+     * Gets the value of the column as an Int.
+     */
     public fun getInt(columnIndex: Int): Int
+
+    /**
+     * Gets the value of the column as a Long.
+     */
     public fun getLong(columnIndex: Int): Long
+
+    /**
+     * Gets the value of the column as a Float.
+     */
     public fun getFloat(columnIndex: Int): Float
+
+    /**
+     * Gets the value of the column as a Double.
+     */
     public fun getDouble(columnIndex: Int): Double
+
+    /**
+     * Gets the value of the column as a String, or null if the column is NULL.
+     */
     public fun getString(columnIndex: Int): String?
+
+    /**
+     * Gets the value of the column as a ByteArray, or null if the column is NULL.
+     */
     public fun getByteArray(columnIndex: Int): ByteArray?
 
+    /**
+     * Gets the zero-based index for the given column name.
+     *
+     * @throws IllegalArgumentException if the column doesn't exist
+     */
     public fun getColumnIndex(columnName: String): Int
 
+    /**
+     * Iterates over all rows, invoking the block with the current row index.
+     */
     public fun forEachRow(block: (Int) -> Unit)
 
+    /**
+     * Moves to the next row.
+     *
+     * @return `true` if the move was successful, `false` if there are no more rows
+     */
     public fun next(): Boolean
 
+    /**
+     * Checks if the column value is NULL.
+     */
     public fun isNull(columnIndex: Int): Boolean
 
+    /**
+     * Closes the cursor and releases resources.
+     */
     public override fun close()
 }