update comment-syntax.md

auto-random.md

@@ -120,7 +120,7 @@ TiDB 支持解析版本注释语法。示例如下：
 {{< copyable "sql" >}}
 
 ```sql
-create table t (a bigint primary key /*T!30100 auto_random */)
+create table t (a bigint primary key /*T![auto_rand] auto_random */)
 ```
 
 {{< copyable "sql" >}}
@@ -131,9 +131,9 @@ create table t (a bigint primary key auto_random)
 
 以上两个语句含义相同。
 
-在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!30100 auto_random */`。其中 `30100` 表示 v3.1.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。
+在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个特性标识符，例如 `/*T![auto_rand] auto_random */`。其中 `auto_rand` 表示 `AUTO_RANDOM` 的特性标识符，只有实现了该标识符对应特性的 TiDB 版本才能够正常解析 SQL 语句片段。
 
-该功能支持向前兼容，即降级兼容。v3.1.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。
+该功能支持向前兼容，即降级兼容。没有实现对应特性的 TiDB 版本则会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。
 
 ## 使用限制
 

comment-syntax.md

@@ -1,105 +1,118 @@
 ---
 title: 注释语法
 category: reference
+summary: 本文介绍 TiDB 支持的注释语法。
 aliases: ['/docs-cn/dev/reference/sql/language-structure/comment-syntax/']
 ---
 
 # 注释语法
 
-TiDB 支持三种注释风格：
-
-* 用 `#` 注释一行
-* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。
-* 用 `/* */` 注释一块，可以注释多行。
-
-例：
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1+1;     # 注释文字
-```
-
-```
-+------+
-| 1+1  |
-+------+
-|    2 |
-+------+
-1 row in set (0.00 sec)
-```
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1+1;     -- 注释文字
-```
-
-```
-+------+
-| 1+1  |
-+------+
-|    2 |
-+------+
-1 row in set (0.00 sec)
-```
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1 /* 这是行内注释文字 */ + 1;
-```
+本文档介绍 TiDB 支持的注释语法。
 
-```
-+--------+
-| 1  + 1 |
-+--------+
-|      2 |
-+--------+
-1 row in set (0.01 sec)
-```
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1+
-    -> /*
-   /*> 这是一条
-   /*> 多行注释
-   /*> */
-    -> 1;
-```
-
-```
-+-------+
-| 1+
-
-1 |
-+-------+
-|     2 |
-+-------+
-1 row in set (0.00 sec)
-```
+TiDB 支持三种注释风格：
 
-{{< copyable "sql" >}}
+* 用 `#` 注释一行：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1;     # 注释文字
+    ```
+
+    ```
+    +------+
+    | 1+1  |
+    +------+
+    |    2 |
+    +------+
+    1 row in set (0.00 sec)
+    ```
+
+* 用 `--` 注释一行：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1;     -- 注释文字
+    ```
+
+    ```
+    +------+
+    | 1+1  |
+    +------+
+    |    2 |
+    +------+
+    1 row in set (0.00 sec)
+    ```
+
+    用 `--` 注释时，必须要在其之后留出至少一个空格，否则注释不生效：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1--1;
+    ```
+
+    ```
+    +--------+
+    | 1+1--1 |
+    +--------+
+    |      3 |
+    +--------+
+    1 row in set (0.01 sec)
+    ```
+
+* 用 `/* */` 注释一块，可以注释多行：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1 /* 这是行内注释文字 */ + 1;
+    ```
+
+    ```
+    +--------+
+    | 1  + 1 |
+    +--------+
+    |      2 |
+    +--------+
+    1 row in set (0.01 sec)
+    ```
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+
+        -> /*
+    /*> 这是一条
+    /*> 多行注释
+    /*> */
+        -> 1;
+    ```
+
+    ```
+    +-------+
+    | 1+
+
+    1 |
+    +-------+
+    |     2 |
+    +-------+
+    1 row in set (0.00 sec)
+    ```
+
+## MySQL 兼容的注释语法
 
-```sql
-SELECT 1+1--1;
-```
+TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
 
 ```
-+--------+
-| 1+1--1 |
-+--------+
-|      3 |
-+--------+
-1 row in set (0.01 sec)
+/*! Specific code */
 ```
 
-TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
+或者
 
 ```
-/*! Specific code */
+/*!50110 Specific code */
 ```
 
 在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。
@@ -108,7 +121,13 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
 
 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...`
 
-如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!30100 XXX */`。
+如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。
+
+## TiDB 可执行的注释语法
+
+TiDB 也有独立的注释语法，称为 TiDB 可执行注释语法，格式为 `/*T![feature_id] XXX */`。只有在当前版本中实现了 `feature_id` 对应的功能特性的 TiDB，才会试图解析该注释里的 SQL 片段。例如 v3.1.1 中引入了 `AUTO_RANDOM` 特性，该版本能够将 `/*T![auto_rand] auto_random */` 解析为 `auto_random`；而 v3.0.0 中没有实现 `AUTO_RANDOM` 特性，则上述 SQL 语句片段会被忽略。
+
+## 优化器注释语法
 
 还有一种注释会被当做是优化器 Hint 特殊对待：
 
@@ -118,8 +137,10 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
 SELECT /*+ hint */ FROM ...;
 ```
 
-由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments
-
 TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md)。
 
-更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。
+> **注意**
+>
+> 由于 TiDB 可执行注释语法和优化器注释语法在 MySQL 客户端 5.7.7 之前的版本中，会被默认当成 comment 清除掉，如果需要在旧的客户端使用这两种语法，需要在启动客户端时加上 --comments 选项，例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。
+
+更多细节，请参考 [MySQL 文档](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。