代码之家 › 专栏 › 技术社区 › HAdes

有没有一种方法可以引用xml注释以避免重复它们?

visual-studio-2008 visual-studio .net c#

HAdes · 技术社区 · 15 年前

这根本不是什么大事,但如果解决了,确实会很有帮助。

当我重载方法等时,有时xml注释完全相同,除了1或2个参数名。我必须将注释复制/粘贴到每个重载方法中,它们是相同的。但是,有时,如果我更新了其中一个方法而忘记返回并将它们复制/粘贴到所有其他方法,这可能会导致有关该方法的误导性信息。如果有很多重载方法,这可能非常耗时,并且容易出错。

所以我想知道是否有一种方法可以将注释存储在一个地方(比如一个变量),我可以直接引用它。这样,一个更改将反映在所有相关的commetn中。

举个例子:

    /// <summary>
    /// Go and do something
    /// </summary>
    public void DoSomething()
    {
        DoSomething(true, "Done something");
    }

    /// <summary>
    /// Go and do something
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    public void DoSomething(bool doIt)
    {
        DoSomething(doIt, "Done something");
    }

    /// <summary>
    /// Go and do something cool
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    /// <param name="doneMessage">message to show once done</param>
    public void DoSomething(bool doIt, string doneMessage)
    {
        if (doIt)
            Console.WriteLine(doneMessage);
    }

所以正如你所看到的,所有的评论都是一样的,只是我决定对最后一条做一个修正,改为“去做些酷的事”。现在我必须去改变这是所有其他方法的评论了。

4 回复 | 直到 15 年前

Reinderien 15 年前

根据这些规范:

http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

XML注释没有固定的标准;那页上显示的只是“推荐”。在推荐的标签中,没有这样的特性。但是,XML文档工具很乐意接受以下内容,没有任何警告:

/// <summary id="30">foo</summary>
void bar();

/// <summary id="30"/>
void bar(int baz);

这对您是否有用取决于您对编译器输出的XML文件做了什么。不幸的是,像Intellisense这样的东西(代码完成和工具提示等)。不会用它做任何事。

编辑:试用 <include> http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx . 它有点重,因为它需要一个单独的文件,但如果您的文档是巨大的,它可能是值得的。

Peter Lillevold Rene 15 年前

在标准XML注释标记中没有这样的函数。 Sandcastle Help File Builder <inheritdoc/> 这就是你要找的。

Paw Baltzersen 15 年前

interface ISomeInterface
{
    /// <summary>Handles this and that.</summary>
    void SomeMethod();

    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary>
    /// <param name="i">Param blabla.</param>
    void SomeMethod(int i);
}

class SomeClass : ISomeInterface
{
    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary>
    public void SomeMethod() { }

    /// <summary><see cref="ISomeInterface.SomeMethod(int)"/></summary>
    public void SomeMethod(int i) { }
}

J0e3gan 12 年前

你说我傻吧,不过是个文档范围的搜索和替换 Go and do something 加上认真使用 + R 中高音 + A

@Reinderien的回答很有帮助……但在以利用IntelliSense或标准处理工具为目标的情况下,这并不是很有帮助。

@Peter Lillevold的回答也很有启发性,我认为更酷的是,它可以和SHFB进行处理……但仍然没有智能感。

@Paw-Baltzersen的答案可以不考虑使用接口而被使用,这很有诱惑力……但是也没有得到正确的智能感知。

我喜欢在可能的情况下避免搜索和替换,但是在这里获得智能感知通常是我首先关心的问题。