[API Compatibility] iinfo/cummax/cummin/diagflat/ldexp/inner/positive/rad2deg/rot90/nanquantile/neg/erf Edit By AI Agent#7878
Merged
zhwesky2010 merged 1 commit intoPaddlePaddle:developfrom Mar 27, 2026
Conversation
zhwesky2010
requested review from
Echo-Nie,
jzhang533,
mattheliu,
ooooo-create and
sunzhongkai588
as code owners
|
感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-7878.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html |
📚 本次 PR 文档预览链接（点击展开）
|
Contributor
There was a problem hiding this comment.
Pull request overview
本 PR 主要面向“API Compatibility”工作流，更新 Coding Agent 的实现指导文档，并同步完善部分 Paddle 中文 API 文档（签名、参数别名、out 关键字参数等），以对齐 PyTorch 风格调用与 out 语义说明。
Changes:
- 更新 API 兼容改造指南：补充 out 参数处理范围、文档描述要求，并强化测试模板的 out 写回检查。
- 更新多篇中文 API 文档：为若干算子补齐
out（keyword-only）签名/说明，并补充 PyTorch 风格别名（如input/dim/other等）。 - 清理/微调部分 API 文档的内容与格式（如段落空行、参数描述等）。
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/dev_guides/coding_agent/api_compatibility/python-decorator.md | 补充 out 参数处理说明与测试模板细节，指导 Python 装饰器兼容改造流程 |
| docs/dev_guides/coding_agent/api_compatibility/cpp-sink.mdr | 同步补充 out 参数文档/测试模板要求，指导 C++ sink 场景改造流程 |
| docs/api/paddle/round_cn.rst | paddle.round 签名增加 keyword-only out，并补充 x 别名与关键字参数段落 |
| docs/api/paddle/rot90_cn.rst | 补充参数别名（如 input/dims）并清理多余空行 |
| docs/api/paddle/rad2deg_cn.rst | 签名增加 keyword-only out，补充别名与关键字参数段落 |
| docs/api/paddle/positive_cn.rst | 签名补充 name 参数，并为 x 增加别名说明 |
| docs/api/paddle/neg_cn.rst | 签名增加 keyword-only out，补充别名与关键字参数段落 |
| docs/api/paddle/nanquantile_cn.rst | 签名增加 keyword-only out，补充别名与关键字参数段落 |
| docs/api/paddle/ldexp_cn.rst | 签名增加 keyword-only out，补充别名与关键字参数段落 |
| docs/api/paddle/inner_cn.rst | 签名增加 keyword-only out，补充别名与关键字参数段落 |
| docs/api/paddle/iinfo_cn.rst | 为 dtype 增加别名 type 的文档说明 |
| docs/api/paddle/erf_cn.rst | 格式与表述调整（含别名标注与返回描述），清理空行 |
| docs/api/paddle/erf__cn.rst | 轻微格式调整（增加空行） |
| docs/api/paddle/diagonal_scatter_cn.rst | 补充参数别名（input/src/dim1/dim2）并清理空行 |
| docs/api/paddle/diagflat_cn.rst | 补充 x 别名与 offset 默认值描述，并清理空行 |
| docs/api/paddle/cummin_cn.rst | 签名增加 keyword-only out，补充 Paddle/PyTorch 两种调用方式、别名与关键字参数段落 |
| docs/api/paddle/cummax_cn.rst | 签名增加 keyword-only out，补充 Paddle/PyTorch 两种调用方式、别名与关键字参数段落 |
Comment on lines
+341
to
+342
| 1. 需在 API 签名中增加 out 参数，`out`参数需与 Pytorch 用法一致，一般情况下 out 均是 keyword-only 参数（使用`*,`分隔），少数情况下 out 是位置参数。 | ||
| 2. 处理 out 参数时，仅需处理 in_dynamic_or_pir_mode()分支下的逻辑，老静态图（LayerHelper）分支无需处理 out 参数。 |
There was a problem hiding this comment.
第 1 条注意事项里存在多处中英文/代码标记之间缺少空格与大小写不一致：例如应写为“out 参数”“PyTorch”“使用 *, 分隔”，以及在 in_dynamic_or_pir_mode() 后与中文之间留空格，避免阅读与检索困难。
Suggested change
| 1. 需在 API 签名中增加 out 参数，`out`参数需与 Pytorch 用法一致，一般情况下 out 均是 keyword-only 参数（使用`*,`分隔），少数情况下 out 是位置参数。 | |
| 2. 处理 out 参数时，仅需处理 in_dynamic_or_pir_mode()分支下的逻辑，老静态图（LayerHelper）分支无需处理 out 参数。 | |
| 1. 需在 API 签名中增加 `out` 参数，`out` 参数需与 PyTorch 用法一致，一般情况下 `out` 均是 keyword-only 参数（使用 `*,` 分隔），少数情况下 `out` 是位置参数。 | |
| 2. 处理 `out` 参数时，仅需处理 `in_dynamic_or_pir_mode()` 分支下的逻辑，老静态图（`LayerHelper`）分支无需处理 `out` 参数。 |
| # 6. out parameter test (only if supported) | ||
| out6 = paddle.empty_like(x) | ||
| out7 = paddle.<api_name>(x, ..., out=out6) | ||
| assert out6 is out7 |
There was a problem hiding this comment.
测试模板在 unittest.TestCase 场景下使用裸 assert 不够稳妥（可能被优化选项禁用、失败信息也不如 unittest 断言清晰）。建议模板改用 self.assertIs(...) / self.assertTrue(...) 等 unittest 断言方法来验证 out 写回语义。
Suggested change
| assert out6 is out7 | |
| self.assertIs(out6, out7) |
Comment on lines
+133
to
+134
| 如果支持了out参数，必须在API文档中描述out参数，out为keyword-only参数（*后面）时注意增加`Keyword Args:`，并在此部分描述。out为位置参数时直接在Args部分描述。如下： | ||
|
|
There was a problem hiding this comment.
该段中文与英文/术语之间缺少必要空格（如“out参数”“API文档”“keyword-only”“Args部分”等），不符合中文文档排版规范，建议统一为“out 参数 / API 文档 / keyword-only 参数 / Args 部分”等。
| ```python | ||
| class Test<APIName>API(unittest.TestCase): | ||
| def setUp(self): | ||
| # If not use random seed, remove setUp |
There was a problem hiding this comment.
测试模板中的英文注释语法不通顺（“If not use …”），建议改为更标准的英文表达或直接使用中文说明。
Suggested change
| # If not use random seed, remove setUp | |
| # If you do not need a random seed, remove setUp |
| # 6. out parameter test (only if supported) | ||
| out6 = paddle.empty_like(x) | ||
| out7 = paddle.<api_name>(x, ..., out=out6) | ||
| assert out6 is out7 |
There was a problem hiding this comment.
同 python-decorator.md 中的模板一致，这里建议不要用裸 assert，改用 unittest 的断言方法（如 self.assertIs）来验证 out 写回语义，避免断言被优化禁用且提升失败信息可读性。
Suggested change
| assert out6 is out7 | |
| self.assertIs(out6, out7) |
|
|
||
| - **x** (Tensor) - 输入的多维 Tensor，数据类型为 float16、float32 或 float64。 | ||
| - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 | ||
| - **x** (Tensor) - 输入 Tensor，数据类型为 float32、float64、uint8、int8、int16、int32、int64。别名: ``input``。 |
There was a problem hiding this comment.
“别名:” 使用了英文冒号，在中文 API 文档中建议统一为中文冒号“别名：”，并在冒号后按仓库常见写法保留空格（如“别名： input。”），避免中英文标点混用。
Suggested change
| - **x** (Tensor) - 输入 Tensor，数据类型为 float32、float64、uint8、int8、int16、int32、int64。别名: ``input``。 | |
| - **x** (Tensor) - 输入 Tensor，数据类型为 float32、float64、uint8、int8、int16、int32、int64。别名： ``input``。 |
| 返回 | ||
| :::::::::: | ||
| - ``out`` (Tensor)：返回累积最大值操作的结果，累积最大值结果类型和输入 x 相同。 | ||
| - ``values`` (Tensor)：返回累积最大值操作的结果，累积最大值结果类型和输入 x 相同。 |
There was a problem hiding this comment.
返回值描述里“输入 x”建议使用 RST inline literal（x）与前文 “Tensor x” 保持一致，避免变量名在渲染后不够醒目。
Suggested change
| - ``values`` (Tensor)：返回累积最大值操作的结果，累积最大值结果类型和输入 x 相同。 | |
| - ``values`` (Tensor)：返回累积最大值操作的结果，累积最大值结果类型和输入 ``x`` 相同。 |
| 返回 | ||
| :::::::::: | ||
| - ``out`` (Tensor)：返回累积最小值操作的结果，累积最小值结果类型和输入 x 相同。 | ||
| - ``values`` (Tensor)：返回累积最小值操作的结果，累积最小值结果类型和输入 x 相同。 |
There was a problem hiding this comment.
返回值描述里“输入 x”建议使用 RST inline literal（x）与前文 “Tensor x” 保持一致，避免变量名在渲染后不够醒目。
Suggested change
| - ``values`` (Tensor)：返回累积最小值操作的结果，累积最小值结果类型和输入 x 相同。 | |
| - ``values`` (Tensor)：返回累积最小值操作的结果，累积最小值结果类型和输入 ``x`` 相同。 |
| ``` | ||
|
|
||
| 如果支持了 out 参数，必须在 API 文档中描述 out 参数，out 为 keyword-only 参数时在 Keyword args 部分描述，为位置参数时在 Args 部分描述，如下： | ||
| 如果支持了 out 参数，必须在 API 文档中描述 out 参数，out 为 keyword-only 参数（*后面）时注意增加`Keyword Args:`，并在此部分描述。out 为位置参数时直接在 Args 部分描述。如下： |
There was a problem hiding this comment.
这句里 “增加Keyword Args:” 前后缺少空格，且英文术语与中文混排建议加空格（如 “keyword-only 参数（* 后面）”“增加 Keyword Args:”），以符合本仓库中文排版规范。
Suggested change
| 如果支持了 out 参数，必须在 API 文档中描述 out 参数，out 为 keyword-only 参数（*后面）时注意增加`Keyword Args:`，并在此部分描述。out 为位置参数时直接在 Args 部分描述。如下： | |
| 如果支持了 out 参数，必须在 API 文档中描述 out 参数，out 为 keyword-only 参数（* 后面）时注意增加 `Keyword Args:`，并在此部分描述。out 为位置参数时直接在 Args 部分描述。如下： |
| ```python | ||
| class Test<APIName>API(unittest.TestCase): | ||
| def setUp(self): | ||
| # If not use random seed, remove setUp |
There was a problem hiding this comment.
测试模板中的英文注释语法不通顺（“If not use …”），建议改为更标准的英文表达或直接使用中文说明，避免被读者误解。
Suggested change
| # If not use random seed, remove setUp | |
| # If you do not need a fixed random seed, remove setUp |
…/rad2deg/rot90/nanquantile/neg/erf Edit By AI Agent
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
API Compatibility Edit By AI Agent：