评论风格（即 Javadocing C# 版本）-（Java 开发者学习 C#）答案

【问题标题】：Commenting Style (i.e. Javadocing C# Version) - (Java Developer Learning C#)评论风格（即 Javadocing C# 版本）-（Java 开发者学习 C#）
【发布时间】：2010-11-07 18:09:55
【问题描述】：

我正在完成我的第一个 C# 类，尽管我继承的原始代码完全没有 cmets，但我在编写 java 时总是将 javadoc cmets 放在我的方法中，并且我的代码目前看起来很奇怪没有这些块.

我通常使用 Eclipse 中的“Insert JavaDoc”命令格式化我的 cmets，该命令简单地布置模板并从运行命令的方法中提取参数、方法名称等。然后我可以从那里添加更多细节。

Visual Studio 2008 中是否有类似的命令？当我在菜单上翻找时，我找不到。此外，在 C# 世界中是否有标准的注释样式约定（类似于 JavaDoc）？

【问题讨论】：

标签： c# visual-studio-2008 comments

【解决方案1】：

有一个免费的 Visual Studio 插件 GhostDoc，它将帮助您创建 C# XML 文档的基本结构，提供比 /// 更多的功能，让您从 Visual Studio 本身获得更多。

【讨论】：

【解决方案2】：

如果您输入///，IDE 编辑器会自动为您生成一个空的 XML 注释。

这个：

///
public QName(String qName, XmlNode contextNode) {

变成这样：

/// <summary>
/// 
/// </summary>
/// <param name="qName"></param>
/// <param name="contextNode"></param>
public QName(String qName, XmlNode contextNode) {

如果您的方法抛出任何异常，您将不得不手动添加标记，因为 .NET 没有声明异常。最后评论：

/// <summary>Creates a new QName from a string with the format
/// <c>prefix:local-name</c> or <c>local-name</c>.</summary>
/// 
/// <param name="qName">A QName string.</param>
/// <param name="contextNode">An XML node from which to lookup the namespace
/// prefix, or <c>null</c>.</param>
/// 
/// <exception cref="XmlInvalidPrefixException">Thrown if the prefix cannot be
/// resolved from the lookup node. If <paramref name="contextNode"/> is
/// <c>null</c>, then the only prefix that can be resolved is <c>xml</c>.
/// </exception>
public QName(String qName, XmlNode contextNode) {

【讨论】：

【解决方案3】：

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

整个特性叫做xml-doc，你可以google很多例子。

【讨论】：

【解决方案4】：

在 C# 中，如果您在要注释的内容顶部输入三个斜杠，它将自动为目标插入适当的文本。

它将包括摘要、参数（如果有）、返回（如果有）等。

///

然后您可以使用 NDoc 之类的东西来获取这些 cmets 并从中构建 API 文档。

【讨论】：

【解决方案5】：

如果您在 Visual Studio 中的方法前键入三个正斜杠“///”，它将自动创建一个简单的模板供您注释方法。（它也会为您创建字段来评论参数和返回值。）我认为这很好，因为它既快速又简单，但您可能需要更深入的内容。

【讨论】：

【解决方案6】：

在任何方法之前键入三个正斜杠：

///

这将生成一个 XML 注释块。

【讨论】：