函数文档编写指南¶
本指南规定 ExcelFlow 参考文档中"函数 / 运算符"条目的格式模板与评估标准，适用于：
目标是让每个函数条目达到同类项目（Google Sheets 函数、PostgreSQL / BigQuery 函数、pandas API）的文档质量。
设计原则¶
- 两层结构：每个分类先给"速查表"（签名 + 一句话用途）便于检索，再给"逐函数详解"。
- 示例可验证：示例要给出"输入值 → 表达式 → 结果"，而不是只给出表达式用法。
- 行为说全：空值输入、错误/严格行为、返回类型必须显式说明，不留给读者推测。
- 与实现一致：签名、参数个数、返回类型必须与
src/excelflow/中的实现逐项对齐。
单个函数条目的格式模板¶
每个函数详解条目使用 ### 标题（函数名作为锚点，便于搜索和深链），包含以下板块：
### `func_name(arg1, arg2[, optional_arg])`
一句话描述函数的作用。
**参数**
| 参数 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `arg1` | 数值 / 字符串 / 日期 / 布尔 / 枚举 | 是 | 该参数的含义与约束。 |
| `optional_arg` | 整数 | 否 | 缺省时的默认值与含义。 |
**返回**：返回类型与含义（例如"浮点数，保留 N 位小数"）。
**示例**
| 输入 | 表达式 | 结果 |
|---|---|---|
| `10.234` | `round(10.234, 2)` | `10.23` |
| 列 `o.amount` | `round(o.amount, 2)` | 逐行四舍五入 |
**备注**：空值输入的返回；是否严格报错；边界与易混点（如与聚合 `min` 的区别）。仅在与默认推断不同时才写。
说明：
- 函数族：语义完全对称的孪生函数（如
upper/lower、ceil/floor、year/month/day）可合并为一个条目，在标题中列出全部签名，正文用"分别执行 …"统一描述，避免重复。 - 速查表：列固定为
函数 | 作用（可附签名），保持紧凑；详解才展开参数与示例。 - 备注板块：若某行为属于整个分类的通用规则（如字符串函数的空值传播），在分类开头用一段散文统一说明，逐函数备注只写该函数特有的差异。
类型标注约定¶
文档中的参数与返回"类型"按 ExcelFlow 语义标注，不写 Pandas 内部 dtype：
| 标注 | 含义 |
|---|---|
| 数值 | 整数或小数 |
| 字符串 | 文本值 |
| 日期 | 日期时间值 |
| 布尔 | True / False |
| 枚举 | 取自固定集合（需在说明中列出可选值） |
| 可空 | 输入或输出可能为缺失值（结合空值行为说明） |
评估标准¶
审核每个函数条目时，逐条核对以下检查项。一个条目应满足全部"必备项"，建议项用于提升质量。
必备项（必须满足）
- 有清晰签名，可选参数用
[]标注。 - 每个参数标注类型与是否必填。
- 说明了返回类型。
- 至少一个示例，且给出"输入 → 表达式 → 结果"，而非仅列表达式。
- 说明了空值（缺失值）输入的返回行为。
- 说明了错误/严格行为（是否让任务失败、是否告警、是否返回空值）。
- 描述与实现一致，无误导（签名、参数个数、返回类型可被源码验证）。
建议项
- 函数名有独立锚点（
###标题），可被搜索和深链命中。 - 与易混函数（如
min_value与聚合min、count与count_all）有显式区分提示。 - 边界与边界值（如负数开方、全空组、零除）有说明。
一个函数条目"达标"= 满足全部必备项。审核产出一张表，记录每个函数对各项的满足情况，未达标项即为改写清单。
分类级要求¶
除逐函数条目外，每个函数分类页应包含：
- 开篇说明该分类函数的共同前提（如字段引用语法、共同空值规则）。
- 一张覆盖全部函数的速查表。
- 一节"限制和错误"，集中说明该分类的全局约束（如不能写聚合函数、不支持自定义函数）。