如何避免CG/HLSL中的文档重复？

Question

假设我们在

CG/HLSL

中几乎没有函数重写，并且这些函数需要一些大且几乎相同的文档，那么如何在不重复相同文本的情况下为每个重写获取它？

/**
* Long general documentation
*/
int do() {...}

/**
* Long general documentation
* @param Value parameter specific documentation
*/
int do(int value) {...}

从解决方案中，我希望将文档放在一个位置，并且能够通过将鼠标悬停在 Rider 等 IDE 中的任何函数名称（在我们的例子中为任何

do

覆盖）上来正确地查看它们。例如。只是像

// see do() function for more info

这样的评论并不是我所期望的。

我尝试了诸如

@ref

、

@see

、

@copydoc

、

@copybrief

等关键字，没有按预期呈现，并且不允许跳转到定义文档的函数。也许问题与我的软件有关，仅供参考，我使用

Unity 2022.3

，

Rider 2024.2

并用

CGPROGRAM

，

.gcinc

书写。

TL;TD:

inheritdoc

中 c#

CG/HLSL

的替代方案是什么？

Answer 1

到目前为止，我提出的解决方法是将通用文档移动到单独的变量中，并进行某种程度的引用。

/**
* Long general documentation
* @related do
*/
int GeneralDoFunctionDocumentation


/** @related GeneralDoFunctionDocumentation */
int do() {...}

/**
* @related GeneralDoFunctionDocumentation
* @param Value parameter specific documentation
*/
int do(int value) {...}

这种方法允许（至少在 Rider 中）跳转到变量定义并通过将鼠标悬停在其上来查看文档，但在许多情况下仍然不方便。