How to Write Functions Documentation.md

CONVERT_TZ

• 本文以CONVERT_TZ为例，说明函数文档的编写要求。
• 如果文档中文字说明部分需要引用语法和示例，则建议使用代码块形式。

功能

将给定的时间转化为另一个时区的时间。

函数功能。

语法

CONVERT_TZ(dt, from_tz, to_tz)

函数语法。

参数说明

• dt ：需要转化的时间。支持的数据类型为 DATETIME。
• from_tz ：源时区名称。支持的数据类型为 VARCHAR。时区可以使用两种格式：时区信息数据库（Time Zone Database，比如 Asia/Shanghai），或 UTC 偏移量（例如+08: 00）。
• to_tz：目标时区名称。支持的数据类型为 VARCHAR。格式同参数 from_tz。

• 格式为 参数：描述+数据类型（请列出所支持的全部数据类型）。
• 描述部分包括参数的含义、是否必选、取值格式、不同数据类型下的取值和单位差异等。
• 数据类型需要大写。

返回值说明

返回值的数据类型为 DATETIME。

• 数据类型需要大写。
• 如有必要，可以适当补充特殊说明，例如：
  • 如果输入值支持不同数据类型，当输入值为不同数据类型时，对应返回值的数据类型或格式。
  • 如果输入值不满足数据类型的要求，则其返回结果是什么，比如 NULL，报错。

注意事项 （可选）

各时区对应的时区信息数据库，请参见时区数据库（来源：维基百科）。

使用该函数时的注意事项（可选）。

示例

示例一：将上海时间转化为洛杉矶时间。

MySQL > select convert_tz('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles');
        -> 2019-07-31 22:21:03                                                       |

示例二：将东八区时间转化为洛杉矶时间。

MySQL > select convert_tz('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles');
+--------------------------------------------------------------------+
| convert_tz('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles') |
+--------------------------------------------------------------------+
| 2019-07-31 22:21:03                                                |
+--------------------------------------------------------------------+

• 需要说明各个示例的作用。
• 如果一个示例中包含多个应用场景，可在示例中加上注解，便于用户快速区分场景。
• 示例的返回结果如果较简单，则建议采用示例一的展现形式；如果较复杂，则建议采用示例二的展现形式。