Skip to content

How to Write Functions Documentation.md

Latest commit

 

History

History
70 lines (48 loc) · 3.05 KB

How to Write Functions Documentation.md

File metadata and controls

70 lines (48 loc) · 3.05 KB

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。

返回值说明

返回值的数据类型为 DATETIME。 返回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                                                |
+--------------------------------------------------------------------+
  • 需要说明每个示例的作用和目的，让用户快速了解该示例场景。
  • 不同示例的代码需要放在不同的代码块里。
  • 如果一个示例中包含多个应用场景，可在示例中加上注解，便于用户快速区分场景。
  • 示例的返回结果如果较简单，则建议采用示例一的展现形式；如果较复杂，则建议采用示例二的展现形式。
  • *正文描述中参数和参数值使用code format (``)包裹。