CG/HLSL中如何避免文档重复？求C# `inheritdoc`替代方案

针对Unity 2022.3 + Rider 2024.2环境下的.gcinc文件开发，以下是两种可行的文档复用方案：

方案一：正确使用@copydoc关键字（推荐） #

Rider对HLSL的Doxygen风格注释支持@copydoc，但需要明确指定目标函数的完整签名（包括返回值、函数名和参数列表）来区分重载。

示例代码：

/**
* Long general documentation
* 这里可以包含函数的通用功能描述、返回值说明等
*/
int do() {...}

/**
* @copydoc int do()
* @param Value 该参数的专属说明，会追加到通用文档之后
*/
int do(int value) {...}

注意事项：

• 目标函数的签名必须完全匹配，比如主函数是float do(float a)，引用时就要写@copydoc float do(float a)
• 确保Rider的HLSL文档解析设置为Doxygen风格（可在Settings > Languages & Frameworks > HLSL > Documentation Comments中确认）

方案二：预处理器宏复用通用文档 #

通过定义宏来封装通用文档内容，在每个重载的注释中引用宏，再补充专属参数说明。

示例代码：

// 定义通用文档宏，注意每行末尾的反斜杠用于换行续接
#define DO_GENERAL_DOC /** \
* Long general documentation \
* 通用的函数功能说明、返回值描述等内容 \
*/

// 主函数直接使用宏
DO_GENERAL_DOC
int do() {...}

// 重载函数先引用宏，再追加专属参数注释
DO_GENERAL_DOC
/**
* @param Value 该参数的专属说明
*/
int do(int value) {...}

注意事项：

• 宏内的文档注释要严格用反斜杠续接，避免语法错误
• Rider会解析宏展开后的注释内容，悬停时能正常显示完整文档

额外提示 #

如果之前使用@copydoc无效，大概率是因为没有指定完整的函数签名，或者Rider的HLSL文档设置未启用Doxygen支持。可以先检查Rider的HLSL相关设置，确保文档注释风格匹配。

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