Question

我正在记录C＃应用程序并遇到以下麻烦。我评论了一个字段，它定义了：

/// <summary>
/// My very detailed description of this field.
/// </summary>
public float myField;

但在其他地方，我引用了这个字段：

///<summary>
/// Modifies the value of <see cref="myField">. 
///</summary>
public void MyMethod()
{
    ...
}

问题是，调用MyMethod（）的用户必须转到myField的定义才能看到它实际上是什么。如果我可以将myField中摘要标记的内容直接复制到MyMethod（）的描述中会好得多。

支持吗？有没有好的选择？

提前致谢。

Answer 1

我担心这种情况你无能为力。

您的主要选项是根本不记录（不推荐！），引用它（最终用户的麻烦），或复制或重新陈述文档（麻烦）。

在这种情况下，我通常会写一个简短的描述，提醒最终用户该变量是什么，而不必复制整个详细描述，例如： Modifies the value of <see cref="myField">, which sets the speed of the doodad。

或者，如果您想要一种自动复制原始文档的方法，我写了一个添加内容，您可以尝试查看它是否符合您的需求 - Atomineer Pro Documentation。它是一个创建和更新文档注释的工具，它会尽可能地从类或基类中的其他位置复制有用的文档。

例如，如果您定义这样的属性：

/// <summary> Speed of the doodad in m/s, in the range 0.0 - 3.7 </summary>
double DoodadSpeed { get; set; }

...然后在相同的类中编写一个方法，该方法具有匹配名称的参数：

void SetNewSpeed(double doodadSpeed)
{
}

...然后Atomineer会在记录参数时自动获取同名属性的描述，为您提供如下内容：

/// <param name="doodadSpeed"> Speed of the doodad in m/s, in the range 0.0 - 3.7 </param>

为此，您需要为您的类使用的每个唯一值（成员，属性，参数）使用唯一名称，以便此方法可以使用。当然，如果名称不匹配，它将无法工作，例如在这些情况下它不会帮助您：

SetNewSpeed(int newSpeed) { }
ModifyDoodadSpeedInSomeWay() { }

（因此在您发布的具体示例中可能没有帮助，因为方法和成员变量之间没有明显的联系 - 但我不知道有什么可以帮助您自动化该案例）