6

我正在编写一个 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)
    {
        ...
    }
}

谢谢

4

3 回答 3

4

“<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

于 2014-10-17T00:01:10.753 回答
1

我认为 Visual Studio 中没有任何东西可以帮助您。Sandcastle有一个标签，inheritdoc，它可以让你继承整个 xml 注释块，或者你也可以定义一个包含你的参数文本的 sandcastle令牌，它可以让你编写类似的东西

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

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

于 2013-06-18T15:30:31.113 回答
0

您可以使用<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属性。我看到的例子让它看起来很不可读，而且对于我自己的使用来说，这可能是一种比问题更糟糕的治疗方法。

于 2022-01-19T15:29:20.740 回答