update README

Author: zhangzhengtian02

README.md

@@ -8,6 +8,147 @@ Kotlin IR Dissector(K.I.D)是一个用于编译期 transform Kotlin IR 的工具
 
 ## 安装
 
+settings.gradle 中添加仓库源
+```kotlin
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+```
+
+工程中依赖插件
+```kotlin
+plugins {
+  id("io.github.androidzzt.kid-plugin") version <latest_version>
+}
+```
+
+KMP(Kotlin Multiplatform) 工程中依赖注解库
+```kotlin
+kotlin {
+  sourceSets {
+    val commonMain by getting {
+      dependencies {
+        implementation("io.github.androidzzt.kid:kid-annotation:<latest_version>")
+      }
+    }
+  }
+}
+```
+
+Kotlin Android(JVM) 工程中依赖注解库
+```kotlin
+dependencies {
+  implementation("io.github.androidzzt.kid:kid-annotation:<latest_version>")
+}
+```
+
 ## 功能
 
-## 示例
+### 1. Hook 目标方法入口
+
+```kotlin
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.SOURCE)
+annotation class EntryHook(
+    val className: String, // 目标方法所在类的全限定名
+    val methodName: String, // 目标方法名
+    val paramsTypes: String, // 目标方法参数类型列表，以逗号分隔
+    val ignoreSuper: Boolean = false // 是否忽略调用 super
+)
+```
+
+比如，现在有 `com.example.Logger#log` 方法，定义如下：
+```kotlin
+package com.example
+
+class Logger {
+  val tag = "Logger"
+  fun log(msg: String) {
+    println(msg)
+  }
+}
+```
+我们想要 hook log 方法的入口，可以这样写：
+```kotlin
+import com.example.Logger
+import com.zzt.kid.annotation.EntryHook
+import com.zzt.kid.runtime.MethodHook
+
+object LoggerEntryHook {
+  @EntryHook(
+    className = "com.example.Logger",
+    methodName = "log",
+    paramsTypes = "(kotlin.String)" // 注意，这里的参数类型需要加上括号，如果有多个参数，以逗号分隔
+  )
+  fun hookLogEntry(caller: Logger, msg: String): MethodHook<Unit> {
+    println("entry: ${caller.tag}:: msg=$msg")
+    return MethodHook.intercept() // 返回 MethodHook.intercept() 表示拦截目标方法，不再执行
+  }
+}
+```
+
+上面代码中有一个类 `MethodHook`, 定义如下：
+```kotlin
+class MethodHook<T>(val ret: T? = null) {
+  var pass: Boolean = ret == null
+
+  companion object {
+    fun <T> pass() = MethodHook<T>(null).apply { pass = true }
+    fun <T> intercept(ret: T? = null) = MethodHook(ret)
+  }
+}
+```
+- 泛型 T 是目标方法的返回类型，如果目标方法无返回类型，那么 T 就是 Unit
+- `MethodHook.pass()` 表示继续执行目标方法
+- `MethodHook.intercept()` 表示拦截目标方法，不再执行，如果目标方法有返回值，可以通过 `MethodHook.intercept(ret)` 来指定返回值
+
+经过 LogEntryHook 的处理后，Logger#log 方法的实现变成了这样：
+```kotlin
+package com.example
+
+class Logger {
+  val tag = "Logger"
+  fun log(msg: String) {
+    val methodHook = LoggerEntryHook.hookLogEntry(this, msg)
+    if (methodHook.pass) {
+      println(msg)
+    }
+  }
+}
+```
+
+### 2. 完全替换目标方法
+
+```kotlin
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.SOURCE)
+annotation class Replace(
+  val className: String, // 目标方法所在类的全限定名
+  val methodName: String, // 目标方法名
+  val paramsTypes: String, // 目标方法参数类型列表，以逗号分隔
+  val ignoreSuper: Boolean = false // 是否忽略调用 super
+)
+```
+
+比如，我们认为 log 方法内部可能出现异常，我们想替换 log 方法，让它在出现异常时打印异常信息，可以这样写：
+```kotlin
+object LoggerHook { 
+    @Replace(
+        className = "com.example.Logger",
+        methodName = "log",
+        paramsTypes = "(kotlin.String)"
+    )
+    fun replaceLog(caller: Logger, msg: String) {
+        try {
+          println(msg)
+        } catch (e: Exception) {
+          e.printStackTrace()
+        }
+    }
+}
+```
+注意，@Replace 不需要配合 MethodHook 使用，插件会将目标方法的实现完全替换成注解方法的实现。
+

README_EN.md

@@ -7,6 +7,147 @@ Kotlin IR Dissector(K.I.D) is a tool for transforming Kotlin IR at compile time.
 
 ## Installation
 
+add repositories in settings.gradle 
+```kotlin
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+```
+
+add plugin in project
+```kotlin
+plugins {
+  id("io.github.androidzzt.kid-plugin") version <latest_version>
+}
+```
+
+add anno dependencies in KMP(Kotlin Multiplatform) project
+```kotlin
+kotlin {
+  sourceSets {
+    val commonMain by getting {
+      dependencies {
+        implementation("io.github.androidzzt.kid:kid-annotation:<latest_version>")
+      }
+    }
+  }
+}
+```
+
+add anno dependencies in Android(JVM) project
+```kotlin
+dependencies {
+  implementation("io.github.androidzzt.kid:kid-annotation:<latest_version>")
+}
+```
+
 ## Features
 
-## Sample
+### 1. Hook target method entry
+
+```kotlin   
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.SOURCE)
+annotation class EntryHook(
+    val className: String, // target method class name
+    val methodName: String, // target method name
+    val paramsTypes: String, // target method params types, separated by commas
+    val ignoreSuper: Boolean = false // ignore super call
+)
+```
+
+for example, there is a method `com.example.Logger#log`:
+```kotlin
+package com.example
+
+class Logger {
+  val tag = "Logger"
+  fun log(msg: String) {
+    println(msg)
+  }
+}
+```
+
+we want to hook the entry of log method, we can write like this:
+```kotlin
+import com.example.Logger
+import com.zzt.kid.annotation.EntryHook
+import com.zzt.kid.runtime.MethodHook
+
+object LoggerEntryHook {
+  @EntryHook(
+    className = "com.example.Logger",
+    methodName = "log",
+    paramsTypes = "(kotlin.String)" // 注意，这里的参数类型需要加上括号，如果有多个参数，以逗号分隔
+  )
+  fun hookLogEntry(caller: Logger, msg: String): MethodHook<Unit> {
+    println("entry: ${caller.tag}:: msg=$msg")
+    return MethodHook.intercept() // 返回 MethodHook.intercept() 表示拦截目标方法，不再执行
+  }
+}
+```
+
+the `MethodHook` class is defined as follows:
+```kotlin
+class MethodHook<T>(val ret: T? = null) {
+  var pass: Boolean = ret == null
+
+  companion object {
+    fun <T> pass() = MethodHook<T>(null).apply { pass = true }
+    fun <T> intercept(ret: T? = null) = MethodHook(ret)
+  }
+}
+```
+- generic T is the return type of the target method, if the target method has no return type, then T is Unit
+- `MethodHook.pass()` means continue to execute the target method
+- `MethodHook.intercept()` means intercept the target method, if the target method has a return value, you can specify the return value through `MethodHook.intercept(ret)`
+
+after the above code is compiled, the implementation of Logger#log method will become like this:
+```kotlin
+package com.example
+
+class Logger {
+  val tag = "Logger"
+  fun log(msg: String) {
+    val methodHook = LoggerEntryHook.hookLogEntry(this, msg)
+    if (methodHook.pass) {
+      println(msg)
+    }
+  }
+}
+```
+
+### 2. Replace target method completely
+
+```kotlin
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.SOURCE)
+annotation class Replace(
+  val className: String, // 目标方法所在类的全限定名
+  val methodName: String, // 目标方法名
+  val paramsTypes: String, // 目标方法参数类型列表，以逗号分隔
+  val ignoreSuper: Boolean = false // 是否忽略调用 super
+)
+```
+
+for example, we think that an exception may occur in the log method, and we want to replace the log method to print the exception information when an exception occurs. We can write like this:
+```kotlin
+object LoggerHook { 
+    @Replace(
+        className = "com.example.Logger",
+        methodName = "log",
+        paramsTypes = "(kotlin.String)"
+    )
+    fun replaceLog(caller: Logger, msg: String) {
+        try {
+          println(msg)
+        } catch (e: Exception) {
+          e.printStackTrace()
+        }
+    }
+}
+```
+Be careful, @Replace does not need to be used with MethodHook. The plugin will completely replace the implementation of the target method with the implementation of the annotation method.