C#带out参数的方法如何在XML注释中正确标识out输出参数

C#官方XML注释规范没有提供原生标签/属性专门标记参数的传递方向（out/ref/in），Visual Studio自动生成的三斜杠注释模板默认也不会主动区分参数方向，针对Swagger这类仅读取注释内容、不解析方法签名的工具场景，可参考以下合规方案：

• 通用兼容方案：直接在对应<param>标签的描述文本开头明确标注参数方向，这是开发场景中最常用、无任何兼容问题的做法，示例如下：

/// <summary>
/// 执行对应业务逻辑的方法
/// </summary>
/// <param name="param1">入参：传入的字符串类型参数</param>
/// <param name="param2">出参：方法执行后返回的ulong类型结果，固定返回值为103206309</param>
/// <returns>布尔值，代表方法执行是否成功</returns>
public static bool theFunction(string param1, out ulong param2) {
  param2 = 103206309L; 
  return true;  
}

这种写法对所有XML注释解析工具（Swagger、DocFX、Sandcastle等）全兼容，不需要额外修改工具配置，阅读文档的开发者可以第一时间识别参数属性。如果团队有统一规范，也可以用[入参]/[出参]这类固定前缀做标注，全项目保持格式统一即可。

• 针对Swagger场景的优化：如果使用Swashbuckle.AspNetCore等常用组件生成Swagger文档，组件默认会读取方法签名元数据，自动识别out参数并标记为输出属性，不需要手动在注释中额外标注。如果出现未识别的情况，优先检查组件配置是否关闭了方法签名元数据读取，不需要强行修改注释内容。
• 避坑提示：不要自行给<param>标签添加非标准的自定义属性（比如direction="out"），这类自定义属性不属于官方XML注释规范范畴，绝大多数文档解析工具都会直接忽略，反而会破坏注释的规范性。

内容的提问来源于stack exchange，提问作者Robert Achmann