C# XML 注释重用

Question

我正在编写一个 C# 类库，其中包含许多具有相同功能的类。 我需要为每个类中的函数参数提供 XML 注释，这些注释非常详细，但在大多数情况下是相同的。 有没有办法重用 XML 注释，这样我就不必在整个程序集中重复这些 XML 参数定义？

这是我的课程的一个例子：

public class IsodoseControl : TestModule
{
    /// <summary>
    /// Verify a control on Isodose dialog
    /// </summary>
    /// <param name="args">  **<-- WHAT I DON'T WANT TO KEEP REPEATING**
    /// Arguments: [Property, Condition, Expected Value, Tolerance]
    ///            Properties: STATE, VALUE, LABEL
    ///            Conditions: Exists, DoesNotExist, IsEnabled, IsDisabled, ...
    ///            Expected Value (optional): blah blah
    ///            Tolerance (optional): blah blah blah
    /// </param>
    public VerifResult VerifyIsodoseControl(string[] args)
    {
        ...
    }
}

public class BeamControl : TestModule
{
    /// <summary>
    /// Verify a control on Beam dialog
    /// </summary>
    /// <param name="args">  **<-- WHAT I DON'T WANT TO KEEP REPEATING**
    /// Arguments: [Property, Condition, Expected Value, Tolerance]
    ///            Properties: STATE, VALUE, LABEL
    ///            Conditions: Exists, DoesNotExist, IsEnabled, IsDisabled, ...
    ///            Expected Value (optional): blah blah
    ///            Tolerance (optional): blah blah blah
    /// </param>
    public VerifResult VerifyBeamControl(string[] args)
    {
        ...
    }
}

谢谢

Answer 1

我认为Visual Studio中没有任何东西可以帮助您。 沙堡有一个标签， inheritdoc ，这将让你继承的XML注释整块，或者你可能还定义了一个沙堡令牌包含您的PARAM文本，这将让你喜欢写东西

/// <summary>
/// Verify a control on Beam dialog
/// </summary>
/// <param name="args"><token>CommonParamInfo</token></param>
/// (...)

Sandcastle专门针对API文档而设计，但可能不适合您的情况。

Answer 2

“<include>标签允许您引用另一个描述源代码中类型和成员的文件中的注释。”

您可以使用<include>标记从两个类中引用相同的文件。

/// <include file='comments.xml' path='MyDocs/MyMembers[@name="test"]/*' />
class OneClass {}

/// <include file='comments.xml' path='MyDocs/MyMembers[@name="test"]/*' />
class DifferentClassWithTheSameFunctionality {}

此链接提供了一些使用<include>的示例： http ： //msdn.microsoft.com/en-us/library/9h8dy30z.aspx

Answer 3

您可以使用<inheritdoc .../>来非常接近。 它似乎主要仅限于仅复制整个文档条目，但有了这个 + 一些谨慎的措辞，也许它可以工作。

（稍微修改的措辞肯定比由于忽视手动维护而逐渐过时的文档要好得多。）

<inheritdoc>

XML

<inheritdoc [cref=""] [path=""]/>

从基类、接口和类似方法继承 XML 注释。 使用inheritdoc 消除了不必要的复制和粘贴重复的XML 注释，并自动保持XML 注释同步。

...

cref ：指定要从中继承文档的成员。 当前成员上已经定义的标签不会被继承的标签覆盖。

path ：XPath 表达式查询将导致节点集显示。 您可以使用此属性过滤要从继承的文档中包含或排除的标签。

...

参考： https ://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags#inheritdoc

当您开始输入cref的值时，您将获得智能感知。 完全有可能（从我刚刚做的快速测试）在那里指定一个namespace.classname.methodname ，以便它可以引用一个完全不同的类。

因此，在问题的示例中，您可以执行以下操作：

    public class IsodoseControl : TestModule
    {
        /// <summary>
        /// Verify a control on the dialog
        /// </summary>
        /// <param name="args">
        /// Arguments: [Property, Condition, Expected Value, Tolerance]
        ///            Properties: STATE, VALUE, LABEL
        ///            Conditions: Exists, DoesNotExist, IsEnabled, IsDisabled, ...
        ///            Expected Value (optional): blah blah
        ///            Tolerance (optional): blah blah blah
        /// </param>
        public VerifResult VerifyIsodoseControl(string[] args)
        {
            ///...
        }
    }

    public class BeamControl : TestModule
    {
        /// <inheritdoc cref="IsodoseControl.VerifyIsodoseControl" />
        public VerifResult VerifyBeamControl(string[] args)
        {
            // ...
        }
    }

为此，我刚刚从“验证...上的控件”句子中删除了“等剂量”一词。 如果这样的改写足够清晰，您必须在自己的代码中做出决定。

以下是显示文档的VerifyBeamControl()智能感知的显示方式：

---

我没有尝试使用path属性。 我看到的例子让它看起来很不可读，而且对于我自己的使用来说，这可能是一种比问题更糟糕的治疗方法。