61 lines
3.0 KiB
Plaintext
61 lines
3.0 KiB
Plaintext
你是一个资深 C# 工程师。现在我会给你一个 missing-csharp-docs.txt 文件，里面列出了项目中缺少 XML 文档注释的 C# 类型、方法、属性、字段、构造函数、接口成员等。
|
||
|
||
请根据这个 txt 文件逐项读取对应源码文件，并直接修改源码，为缺少注释的成员补全中文 XML 文档注释。
|
||
|
||
要求如下：
|
||
|
||
1. 注释必须是中文。
|
||
2. 使用标准 C# XML 文档注释格式。
|
||
3. 类、接口、record、struct、enum 使用：
|
||
/// <summary>
|
||
/// ...
|
||
/// </summary>
|
||
4. 方法、构造函数必须尽量补全：
|
||
/// <summary>
|
||
/// ...
|
||
/// </summary>
|
||
/// <param name="xxx">...</param>
|
||
/// <returns>...</returns>
|
||
/// <exception cref="...">...</exception>
|
||
5. 如果方法没有参数，不要生成 <param>。
|
||
6. 如果方法返回 void、Task 或构造函数，不要生成无意义的 <returns>。
|
||
7. 如果方法返回 Task<T>、ValueTask<T>、T、IEnumerable<T> 等有实际返回值的类型，需要生成 <returns>，说明返回内容。
|
||
8. 如果方法体中明确 throw 了异常，或声明逻辑明显可能抛出特定异常，可以补充 <exception>；不确定时不要乱写。
|
||
9. 属性使用：
|
||
/// <summary>
|
||
/// 获取或设置...
|
||
/// </summary>
|
||
如果是只读属性，写“获取...”；如果是计算属性，说明它计算或表示的含义。
|
||
10. 字段使用：
|
||
/// <summary>
|
||
/// 保存/定义/指示...
|
||
/// </summary>
|
||
11. 枚举成员也要加中文 summary，说明每个枚举值的含义。
|
||
12. 接口方法必须在 interface 中写完整注释，包括 summary、param、returns。
|
||
13. 具体实现类如果实现了已有注释的接口方法，优先使用：
|
||
/// <inheritdoc />
|
||
不要在实现类重复写一大段相同注释。
|
||
14. 如果实现类方法不是接口实现，或者接口中没有对应注释，则在实现类中写完整注释。
|
||
15. 不要只根据方法名机械生成注释，要结合方法体、参数、返回值、调用逻辑和业务语义来写。
|
||
16. 不要改业务逻辑，不要改方法签名，不要改格式以外的代码。
|
||
17. XML 注释放在 attribute 之前，例如：
|
||
/// <summary>
|
||
/// 用户 ID。
|
||
/// </summary>
|
||
[Column("user-id")]
|
||
public int UserId { get; set; }
|
||
18. 如果成员前已经有 XML 注释，不要重复添加。
|
||
19. 如果 txt 中的行号因为代码变化不准确，要通过成员名称和声明内容定位实际源码位置。
|
||
20. 修改完成后，重新运行已有的注释扫描脚本确认缺失项为 0。
|
||
21. 最后运行相关 dotnet build 验证没有语法错误。
|
||
22. 最后给我总结：修改了哪些文件、补了多少处注释、扫描结果、构建结果。
|
||
|
||
执行方式：
|
||
- 直接读取 missing-csharp-docs.txt。
|
||
- 按 txt 中列出的 File、Line、Kind、Name、Declaration 定位源码成员。
|
||
- 逐文件修改。
|
||
- 不要新建额外的注释生成脚本。
|
||
- 不要生成新的工具脚本。
|
||
- 可以使用现有脚本重新扫描验证。
|
||
- 最终直接完成代码修改。
|