moe descriptions and more faq

docs/zh-cn/doc/frequency-asked-questions.md

@@ -15,7 +15,13 @@
 
 参见Java和Kotlin示例中`DemoInheritTest`测试类的用例。
 
-#### 3. `TestableMock`能否用于Android项目的测试？
+#### 3. 在Kotlin项目对`String`类中的方法进行Mock不生效？
+
+Kotlin语言中的`String`类型实际上是`kotlin.String`，而非`java.lang.String`。但在构建生成自字节码的时候又会被替换为Java的`java.lang.String`类，因此无论将Mock目标写为`kotlin.String`或`java.lang.String`均无法正常匹配到原始的被调用方法。
+
+实际场景中需要对`String`类中的方法进行Mock的场景很少，`TestableMock`暂未对这种情况做特别处理。
+
+#### 4. `TestableMock`能否用于Android项目的测试？
 
 结合[Roboelectric](https://github.com/robolectric/robolectric)测试框架可使用。
 

docs/zh-cn/doc/private-accessor.md

@@ -1,6 +1,10 @@
 访问私有成员字段和方法
 ---
 
+如今关于私有方法是否应该做单元测试的争论正逐渐消停，开发者的普遍实践已经给出事实答案。通过公有方法间接测私有方法在很多情况下难以进行，开发者们更愿意通过修改方法可见性的办法来让原本私有的方法在测试用例中变得可测。
+
+此外，在单元测试中时常会需要对被测对象进行特定的成员字段初始化，但有时由于被测类的构造方法限制，使得无法便捷的对这些字段进行赋值。那么，能否在不破坏被测类型封装的情况下，允许单元测试用例内的代码直接访问被测类的私有方法和成员变量呢？TestableMock提供了一种简单的解决方案。
+
 只需为测试类添加`@EnablePrivateAccess`注解，即可在测试用例中获得以下增强能力：
 
 - 调用被测类的私有方法
@@ -8,8 +12,8 @@
 - 修改被测类的私有成员
 - 修改被测类的常量成员（使用final修饰的成员）
 
-访问和修改私有、常量成员时，IDE可能会提示语法有误，但编译器将能够正常运行测试。
+访问和修改私有、常量成员时，IDE可能会提示语法有误，但编译器将能够正常运行测试。（使用编译期代码增强，目前仅实现了Java语言的适配）
 
-若不希望看到IDE的语法错误提醒，或是在非Java语言的JVM项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。
+若不希望看到IDE的语法错误提醒，或是在非Java语言的JVM工程（譬如Kotlin语言）里，也可以借助`PrivateAccessor`工具类来实现私有成员的访问。
 
 效果见`java-demo`和`kotlin-demo`示例项目`DemoPrivateAccessTest`测试类中的用例。

docs/zh-cn/doc/test-void-method.md

@@ -1,7 +1,9 @@
 测试无返回值的方法
 ---
 
-从功能的角度来说，虽然void方法不返回任何值，但它的执行一定会对外界产生某些"副作用"，比如：
+如何对void类型的方法进行测试一直是许多单元测试框架在悄悄回避的话题，由于以往的单元测试手段主要是对被测单元的返回结果进行校验，当遇到方法没有返回值时就会变得无从下手。
+
+从功能的角度来说，虽然void方法不返回任何值，但它的执行一定会对外界产生某些潜在影响，我们将其称为方法的"副作用"，比如：
 
 1. 初始化某些外部变量（私有成员变量或者全局静态变量）
 2. 在方法体内对外部对象实例进行赋值   
@@ -14,7 +16,7 @@
 
 这些"副作用"归纳来说可分为两类：**修改外部变量**和**调用外部方法**。
 
-通过TestableMock的私有字段访问和Mock校验器可以实现对这些操作的检查。
+通过TestableMock的私有字段访问和Mock校验器可以很方便的实现对"副作用"的结果检查。
 
 #### 修改外部变量的void方法
 

docs/zh-cn/doc/use-mock.md

@@ -1,13 +1,17 @@
 快速Mock被测类的任意方法调用
 ---
 
+相比以往Mock工具以类为粒度的Mock方式，TestableMock允许用户直接定义需要Mock的单个方法，并遵循约定优于配置的原则，按照规则自动在测试运行时替换被测方法中的指定方法调用。
+
+具体的Mock方法定义约定如下：
+
 #### 1. 覆写任意类的方法调用
 
 在测试类里定义一个有`@TestableMock`注解的普通方法，使它与需覆写的方法名称、参数、返回值类型完全一致，然后在其参数列表首位再增加一个类型为该方法原本所属对象类型的参数。
 
 此时被测类中所有对该需覆写方法的调用，将在单元测试运行时，将自动被替换为对上述自定义Mock方法的调用。
 
-**注意**：也可以将需覆写的方法名写到`@TestableMock`注解的`targetMethod`参数里，这样Mock方法自身就可以随意命名了（当遇到重名的待覆写方法时特别有用）。
+**注意**：当遇到待覆写方法有重名时，可以将需覆写的方法名写到`@TestableMock`注解的`targetMethod`参数里，这样Mock方法自身就可以随意命名了。
 
 例如，被测类中有一处`"anything".substring(1, 2)`调用，我们希望在运行测试的时候将它换成一个固定字符串，则只需在测试类定义如下方法：
 
@@ -22,6 +26,17 @@ private String substring(String self, int i, int j) {
 }
 ```
 
+下面这个例子展示了`targetMethod`参数的用法，其效果与上述示例相同：
+
+```java
+// 使用`targetMethod`指定需Mock的方法名
+// 此方法本身现在可以随意命名，但方法参数依然需要遵循相同的匹配规则
+@TestableMock(targetMethod = "substring")
+private String use_any_mock_method_name(String self, int i, int j) {
+    return "sub_string";
+}
+```
+
 完整代码示例见`java-demo`和`kotlin-demo`示例项目中的`should_able_to_mock_common_method()`测试用例。(由于Kotlin对String类型进行了魔改，故Kotlin示例中将被测方法在`BlackBox`类里加了一层封装)
 
 #### 2. 覆写被测类自身的成员方法