是否已发布C＃XML文档的样式指南？

Question

我要求编写C＃代码的开发人员遵循StyleCop的指导原则。这对代码来说很棒，但我几乎总是对文档有疑问（好吧......好吧......所以没有人问，因为程序员往往讨厌文档）风格。我可以建议复制MSDN的风格，但我很好奇微软或其他人是否发布过这方面的内容。

例如，构造函数记录如下。

/// <summary>
/// Initializes a new instance of <c>MyClass</c> using the specified <c>BaseMyClass</c>.
/// </summary>
/// <param name="myParam">The <c>MyParam</c> of the current session.</param>

我不是要在这里引发关于如何编写文档的争论。我正在寻找关于文档建议语法的某种已发布的指南。

提前致谢！

Answer 1

StyleCop FxCop实际上也提供了XML文档的规则。如果你不遵循某组规则设定的模式，它会抱怨。

这些都是规则SA1600-SA1647。

例如，规则SA1642：ConstructorSummaryDocumentationMustBeginWithStandardText声明：

  

非私有实例构造函数的摘要必须以“初始化{class name}类的新实例”开头。

有关详细信息，请参阅FxCop。

Answer 2

如果您需要有关如何以及在何处使用XML文档的一般指南，以下是两个非常有用的链接（我在很多场合已经提到过）。

• MSDN Recommended Tags for Documentation Comments
• C# XML Documentation : Alan Dean（死 - archived version）

我认为这是你想要的那种模糊的东西。关于XML评论的实际措辞和语法，我也在寻找关于这方面的建议/指导，但无济于事。在这方面最好的想法就是遵循.NET BCL（基类库） - 尽管在BCL文档中存在奇怪的不一致。

希望有帮助...

Answer 3

我的visual studio加载项AtomineerUtils将生成并更新XmlDoc注释。

它有一组模板，允许您指定确切的样式（哪些条目对于不同类型的代码元素是合法的，它们列出的顺序，某些条目之间是否有空行以及封闭的样式文件块）。它将删除不再正确的条目（例如删除参数）并添加未记录的功能条目（例如新参数或抛出的异常），并且它将使用自动缩进和自动换行保持文档整洁。

因此，通过使用AU生成和更新您的注释，您可以非常轻松地为文档注释强制执行特定的样式和布局。如果您希望使用StyleCop来强制执行某些文档规则，AtomineerUtils可以选择以StyleCop兼容格式生成文档。

它还可以快速，轻松地记录代码，即使是团队中不太自愿的程序员也更有可能很好地记录代码。