From 1c8357037ca2a0256e905d5b7cf20bf890abf773 Mon Sep 17 00:00:00 2001
From: huangzhhui <huangzhwork@gmail.com>
Date: Thu, 21 Mar 2019 12:16:46 +0800
Subject: [PATCH] Added annotation doc

---
 zh/annotation.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 87 insertions(+), 2 deletions(-)

diff --git a/zh/annotation.md b/zh/annotation.md
index ab0b99871..c4a1408b0 100644
--- a/zh/annotation.md
+++ b/zh/annotation.md
@@ -27,14 +27,99 @@ Hyperf 使用了 [doctrine/annotations](https://github.com/doctrine/annotations)
 
 ## 使用注解
 
+注解一共有3种应用对象，分别是 `类`、`类方法` 和 `类属性`。
+
 ### 使用类注解
 
+类注解定义是在 `class` 关键词上方的注释块内，比如常用的 `@Controller` 和 `@AutoController` 就是类注解的使用典范，下面的代码示例则为一个正确使用类注解的示例，表明 `@ClassAnnotation` 注解应用于 `Foo` 类。   
+```php
+/**
+ * @ClassAnnotation()
+ */
+class Foo {}
+```
+
 ### 使用类方法注解
 
-### 使用属性注解
+类方法注解定义是在方法上方的注释块内，比如常用的 `@RequestMapping` 就是类方法注解的使用典范，下面的代码示例则为一个正确使用类方法注解的示例，表明 `@MethodAnnotation` 注解应用于 `Foo::bar()` 方法。   
+```php
+class Foo
+{
+    /**
+     * @MethodAnnotation()
+     */
+    public function bar()
+    {
+        // some code
+    }
+}
+```
+
+### 使用类属性注解
+
+类属性注解定义是在属性上方的注释块内，比如常用的 `@Value` 和 `@Inject` 就是类属性注解的使用典范，下面的代码示例则为一个正确使用类属性注解的示例，表明 `@MethodAnnotation` 注解应用于 `Foo::bar()` 方法。   
+```php
+class Foo
+{
+    /**
+     * @PropertyAnnotation()
+     */
+    private $bar;
+}
+```
+
+### 注解参数传递
+
+- 传递主要的单个参数 `@DemoAnnotation("value")`
+- 传递字符串参数 `@DemoAnnotation(key1="value1", key2="value2")`
+- 传递数组参数 `@DemoAnnotation(key={"value1", "value2"})`
 
 ## 自定义注解
 
 ### 定义一个自定义注解
 
-#### 自定义注解收集器
\ No newline at end of file
+#### 创建一个注解类
+
+在任意地方创建注解类，如下代码示例：    
+
+```php
+namespace App\Annotations;
+
+use Hyperf\Di\Annotation\AbstractAnnotation;
+
+/**
+ * @Annotation
+ * @Target({"METHOD","PROPERTY"})
+ */
+class Bar extends AbstractAnnotation
+{
+    // some code
+}
+
+/**
+ * @Annotation
+ * @Target("CLASS")
+ */
+class Foo extends AbstractAnnotation
+{
+    // some code
+}
+```
+
+> 注意注解类的 `@Annotation` 和 `@Target` 注解为全局注解，无需 `use` 
+
+其中 `@Target` 有如下参数：   
+- `METHOD` 注解允许定义在类方法上
+- `PROPERTY` 注解允许定义在类属性上
+- `CLASS` 注解允许定义在类上
+- `ALL` 注解允许定义在任何地方
+
+我们注意一下在上面的示例代码中，注解类都继承了 `Hyperf\Di\Annotation\AbstractAnnotation` 抽象类，对于注解类来说，这个不是必须的，但对于 Hyperf 的注解类来说，继承 `Hyperf\Di\Annotation\AnnotationInterface` 接口类是必须的，那么抽象类在这里的作用是提供极简的定义方式，该抽象类已经为您实现了`注解参数自动分配到类属性`、`根据注解使用位置自动按照规则收集到 AnnotationCollector` 这样非常便捷的功能。
+
+#### 自定义注解收集器
+
+注解的收集时具体的执行流程也是在注解类内实现的，相关的方法由 `Hyperf\Di\Annotation\AnnotationInterface` 约束着，该接口类要求了下面 3 个方法的实现，您可以根据自己的需求实现对应的逻辑：
+
+- `public function collectClass(string $className): void;` 当注解定义在类时被扫描时会触发该方法
+- `public function collectMethod(string $className, ?string $target): void;` 当注解定义在类方法时被扫描时会触发该方法
+- `public function collectProperty(string $className, ?string $target): void` 当注解定义在类属性时被扫描时会触发该方法
\ No newline at end of file