如何在VS 2010中为变量/字段/列表编写注释/文档？

Question

有一个问题

///<summary>
///This is summary for some class or method
///</summary>

我需要查看关于类或方法的文档。但是如何为简单变量或列表编写文档?

我使用Visual Studio 2010，当我悬停在某个列表、属性或者其他内容上时，我希望能够看到我为该特定内容编写的摘要（在那个小提示框中）。

///<doc>
///always use this list!
List<String> beer = new List<String>();

编辑：好的，我们已经发现，只要您在类中但在方法或函数之外进行评论，它就像通常一样工作！

有没有办法在方法内部进行文档/评论？

public class BeerForall
{
    /// <summary>
    /// it works here
    /// </summary>
    public List<String> beer = new List<string>();

    public String giveBeer()
    {
        /// is not working, u can not comment
        /// <summary>
        /// test test, not working
        /// </summary>
        List<String> moreBeer = new List<string>();

        return "beer";
    }
}

- Gero

---

对于所有属性和字段，它都能够正常工作，但对于函数中的任何变量可能不起作用？ - gideon

该死，你是对的 :/ 在方法中不起作用。在类中您可以像往常一样记录，但在方法/函数中它不起作用！有什么办法让它起作用吗？ - Gero

它确实适用于方法吗？你的方法定义在哪里，从哪里调用它？如果它在智能感知中显示，注释将会显示。有时可能只需要几秒钟来加载。 - gideon

无法记录局部变量。 - Lasse V. Karlsen

糟糕，没有看到 within 方法，不行。 - gideon

记录实现细节的目的是什么？ - Rhys van der Waerden

Answer 1

正如其他人提到的那样，你无法获取本地变量的智能感知。然而：如果你的函数太大，以致于“常规”注释无法在使用变量的地方附近阅读，那么正确的解决方法是重构函数--将其分解为多个较小的方法，使用较少的变量。我认为这个功能不应该存在，因为它只会促进编写过度庞大的函数。

- Craig Stuntz

---

也许你还没有看到这有什么用处。我建议你看一下doxygen。在doxygen中，你可以在函数前的注释中写任何文档，也可以在函数内部编写。这使得你可以继续例如备注部分，解释算法，并以非常接近于文字编程的风格交错代码和文档。某些代码片段受益匪浅。 - migle

重构代码很好，但我不认为拿走程序员的工具是促进良好编码实践的有用“特性”。就个人而言，我认为这并没有起到作用。我现在维护的代码库的编写者并没有说：“哦，天啊，我不能对局部变量进行注释，所以我现在要写得更好了。”另外，假设这真的是故意省略的以鼓励良好的编程风格，为什么在VS2013中C/C++的局部变量智能感知注释可以工作，但C#却不行呢？ - jrh

“我认为这个功能不应该存在，因为它只会促进编写过度庞大的函数。” 我认为它应该存在，除非你能重写我需要处理的后端代码中的 30k+ 行。 - Maciej Szpakowski

我们实际上正在记录这些变量，以便首先重构巨大的方法，而缺乏这个功能并没有帮助…… - Zar Shardan

有点晚了，但是...如果你只是为了重构而记录它们，那就重新命名它们。30个以上字符名称的变量不适合用于发布的代码，但在重构过程中它们还是可以的。 - Sparr

Answer 2

在Visual Studio 2010中似乎完美地工作。我在MainForm类中定义了一个List作为私有字段，并加上了注释。

但是，它们对于在函数内定义的局部变量无效。

- gideon

---

在类本身中它可以工作。但是尝试在方法内部记录一些内容。请参阅我编辑的第一篇帖子。 - Gero

是的，这就是我在你的问题的第一条评论中所说的，你无法记录在方法内定义的变量。 - gideon

如果能使其适用于局部方法级变量，那将很酷...这样你就可以在本地代码中使用智能感知。我是说，为什么不呢？ - Brady Moritz

Answer 3

据我所知，对于在函数内声明的局部变量添加智能感知注释是不起作用的。如果将您的局部列表作为类的实例变量，那么您就可以做到这一点。

- ooPeanutButter

Answer 4

编辑：看起来 <var> 仅支持 JavaScript。

从 Visual Studio 2012 开始，您可以使用 <var> 元素添加此文档。

这是微软的文档：
https://msdn.microsoft.com/zh-cn/library/hh542722(v=vs.110).aspx

- user2587659

---

不幸的是，链接的文档仅适用于Javascript。我尝试在本地变量上使用<var>，但没有效果。 - John Weisz

Answer 5

与编写类和方法的摘要方式相同，也可以用于变量。

- Pedryk

Answer 6

您可以将此类XML文档注释添加到任何类成员上，而不是在成员（方法、属性等）内部。

- abatishchev