我可以在 Visual Studio 中刷新 XML 注释以反映已更改的参数吗？

Posted 2023-02-21

【中文标题】我可以在 Visual Studio 中刷新 XML 注释以反映已更改的参数吗？

【英文标题】：Can I refresh an XML comment in Visual Studio to reflect parameters that have changed?

【发布时间】：2012-05-14 03:42:46

【问题描述】：

如果我写函数：

    public static uint FindAUint(double firstParam)
    

    

我可以通过键入“///”来生成 xml cmets，它给出了：

    /// <summary>
    /// *Here I type the summary of the method*
    /// </summary>
    /// <param name="firstParam">*Summary of param*</param>
    /// <returns>*Summary of return*</returns>
    public static uint FindAUint(double firstParam)
    

    

如果我决定需要将我的方法更新为：

    /// <summary>
    /// *Here I type the summary of the method*
    /// </summary>
    /// <param name="firstParam">*Summary of param*</param>
    /// <returns>*Summary of return*</returns>
    public static uint FindAUint(double firstParam,double newParam, double newParam2)
    

    

有没有办法让 Visual Studio 将新参数添加到 xml 中而不会丢失以前的描述？

（我应该提到我正在使用 Visual Studio Express；不过，我不会让微软在 Express 版本中禁止该功能）

【问题讨论】：

AFAIK，你是不是在用VS，你得手动输入他们

如果您键入<param name="，它只会使用您当前没有记录的参数列表填充 IntelliSense 窗口。不是解决方案，只是一个可能有帮助的方便提示。

【参考方案1】：

查看GhostDoc。它是一个 Visual Studio 扩展，可为您生成 XML cmets。

【讨论】：

是否会保留现有的 cmets，并且只为新参数添加 XML？

它将删除不再存在的参数的 cmets 并添加任何缺少的参数。它不会覆盖任何东西。它还将生成方法、属性、参数等的默认描述。

如果没有 GhostDoc 和 Resharper，我将无法在 Visual Studio 中工作。

@NominSim 如果您是专业编写代码，那么您真的应该拥有完整版。我相信 Express 适合学生和非商业用途。

@cadrell0 Express 没有许可限制，还没有看到真正需要获得完整版本，因为（尽管有一些跳跃）我需要做的就是用 Express 完成。

【参考方案2】：

ReSharper 非常适合我；只要 XML 注释与方法的签名不匹配，它就会发出警告。

此外，使用 ALT + ENTER 键盘快捷键，ReSharper 可以通过添加/删除必要的 XML cmets 来修复这些不匹配。

【讨论】：

我只看到这种方法的一个缺点；如果方法在 xml cmets 中没有任何 部分，即使方法中有参数，Resharper 也不会建议添加缺少的参数。但无论如何，+1 :)

【参考方案3】：

一种解决方法是选择 XML 文档的当前块并将其注释掉。然后在注释掉的代码下创建一个新行。将使用所有新值创建一个新的 XML 文档块，您可以复制粘贴旧值。

例子：

/// <summary>
/// Does something
/// </summary>
/// <param name="bar">True if not false</param>
/// <returns>Some really important value</returns>
public bool Foo(bool bar) 
    return bar;

方法的改变

/// <summary>
/// Does something
/// </summary>
/// <param name="bar">True if not false</param>
/// <returns>Some really important name</returns>
public string Foo(bool bar, string bar2, int bar3) 
    if (bar) 
        return bar2 + bar3.ToString();
     else 
        return "foobar";
    

注释掉文档

///// <summary>
///// Does something
///// </summary>
///// <param name="bar">True if not false</param>
///// <returns>Some really important name</returns>
public string Foo(bool bar, string bar2, int bar3) 
    if (bar) 
        return bar2 + bar3.ToString();
     else 
        return "foobar";
    

在注释掉的代码下的新行中输入 /// 以获取生成的 XML 文档。

///// <summary>
///// Does something
///// </summary>
///// <param name="bar">True if not false</param>
///// <returns>Some really important value</returns>
/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
/// <param name="bar2"></param>
/// <param name="bar3"></param>
/// <returns></returns>
public string Foo(bool bar, string bar2, int bar3) 
    if (bar) 
        return bar2 + bar3.ToString();
     else 
        return "foobar";