comment-syntax: add TiDB-specific comment syntax (#3238)

comment-syntax.md

@@ -1,75 +1,119 @@
 ---
 title: Comment Syntax
-summary: Learn about the three comment styles in TiDB.
+summary: This document introduces the comment syntax supported by TiDB.
 aliases: ['/docs/v3.0/comment-syntax/','/docs/v3.0/reference/sql/language-structure/comment-syntax/','/docs/sql/comment-syntax/']
 ---
 
 # Comment Syntax
 
-TiDB supports three comment styles:
+This document describes the comment syntax supported by TiDB.
 
-- Use `#` to comment a line.
-- Use `--` to comment a line, and this style requires at least one whitespace after `--`.
-- Use `/* */` to comment a block or multiple lines.
+TiDB supports three comment styles:
 
-Example:
+- Use `#` to comment a line:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1;     # comments
+    ```
+
+    ```
+    +------+
+    | 1+1  |
+    +------+
+    |    2 |
+    +------+
+    1 row in set (0.00 sec)
+    ```
+
+- Use `--` to comment a line:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1;     -- comments
+    ```
+
+    ```
+    +------+
+    | 1+1  |
+    +------+
+    |    2 |
+    +------+
+    1 row in set (0.00 sec)
+    ```
+
+    And this style requires at least one whitespace after `--`:
+
+   {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1--1;
+    ```
+
+    ```
+    +--------+
+    | 1+1--1 |
+    +--------+
+    |      3 |
+    +--------+
+    1 row in set (0.01 sec)
+    ```
+
+- Use `/* */` to comment a block or multiple lines:
+
+   {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1 /* this is an in-line comment */ + 1;
+    ```
+
+    ```
+    +--------+
+    | 1  + 1 |
+    +--------+
+    |      2 |
+    +--------+
+    1 row in set (0.01 sec)
+    ```
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+
+        -> /*
+    /*> this is a
+    /*> multiple-line comment
+    /*> */
+        -> 1;
+    ```
+
+    ```
+    +-------+
+    | 1+
+    1 |
+    +-------+
+    |     2 |
+    +-------+
+    1 row in set (0.00 sec)
+    ```
+
+## MySQL-compatible comment syntax
+
+The same as MySQL, TiDB supports a variant of C comment style:
 
-```sql
-mysql> SELECT 1+1;     # This comment continues to the end of line
-+------+
-| 1+1  |
-+------+
-|    2 |
-+------+
-1 row in set (0.00 sec)
-
-mysql> SELECT 1+1;     -- This comment continues to the end of line
-+------+
-| 1+1  |
-+------+
-|    2 |
-+------+
-1 row in set (0.00 sec)
-
-mysql> SELECT 1 /* this is an in-line comment */ + 1;
-+--------+
-| 1  + 1 |
-+--------+
-|      2 |
-+--------+
-1 row in set (0.01 sec)
-
-mysql> SELECT 1+
-    -> /*
-   /*> this is a
-   /*> multiple-line comment
-   /*> */
-    -> 1;
-+-------+
-| 1+
-
-1 |
-+-------+
-|     2 |
-+-------+
-1 row in set (0.00 sec)
-
-mysql> SELECT 1+1--1;
-+--------+
-| 1+1--1 |
-+--------+
-|      3 |
-+--------+
-1 row in set (0.01 sec)
+```
+/*! Specific code */
 ```
 
-Similar to MySQL, TiDB supports a variant of C comment style:
+or
 
 ```
-/*! Specific code */
+/*!50110 Specific code */
 ```
 
-In this comment style, TiDB runs the statements in the comment. The syntax is used to make these SQL statements ignored in other databases and run only in TiDB.
+In this style, TiDB runs the statements in the comment.
 
 For example:
 
@@ -83,20 +127,26 @@ In TiDB, you can also use another version:
 SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...
 ```
 
-If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the version number does not work and all contents in the comment are processed.
+If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment are processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. 
 
-Another type of comment is specially treated as the Hint optimizer:
+## TiDB specific comment syntax
 
-```
-SELECT /*+ hint */ FROM ...;
-```
+TiDB has its own comment syntax (that is, TiDB specific comment syntax) with the format of `/*T![feature_id] XXX */`. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version of TiDB can parse `/*T![auto_rand] auto_random */` into `auto_random`. Because the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored.
 
-Since Hint is involved in comments like `/*+ xxx */`, the MySQL client clears the comment by default in versions earlier than 5.7.7. To use Hint in those earlier versions, add the `--comments` option when you start the client. For example:
+## Optimizer comment syntax
 
-```
-mysql -h 127.0.0.1 -P 4000 -uroot --comments
+Another type of comment is specially treated as an optimizer hint:
+
+{{< copyable "sql" >}}
+
+```sql
+SELECT /*+ hint */ FROM ...;
 ```
 
 For details about the optimizer hints that TiDB supports, see [Optimizer hints](/optimizer-hints.md).
 
+> **Note**
+>
+> In MySQL client before 5.7.7, TiDB specific comment syntax and optimizer comment syntax are treated as comments and cleared by default. To use the two syntaxes in the old client, add the `--comments` option when you start the client. For example, `mysql -h 127.0.0.1 -P 4000 -uroot --comments`.
+
 For more information, see [Comment Syntax](https://dev.mysql.com/doc/refman/5.7/en/comments.html).