如何强制文档评论答案

【问题标题】：How do I force document comment如何强制文档评论
【发布时间】：2016-10-13 15:10:57
【问题描述】：

我有一个很少有开发人员可以编辑和添加新方法的 SDK。我想强制每个添加新功能的开发人员添加文档注释。记录在案的评论应包括此方法的受支持版本。对于摘要，我添加了 XML 文档文件，它对我有用（如果没有记录注释，则构建失败）支持的版本评论我还是没有解决办法

    /// <summary>
    /// Function1 description
    /// </summary>
    /// <**supportedSince**>Version 5.6</**supportedSince**>
    public List<string> Function1{ get; set; }

【问题讨论】：

AFAIK，stylecop 可以做到这一点。您可以在您使用的 SCM 中设置 pre-commit/pre-push 挂钩。

标签： c# visual-studio

【解决方案1】：

Warning CS1591在XML comments are missing时生成

您可以将单个警告视为错误 - 必须对使用相关源代码的每个项目执行此操作。见/warnaserror

因此您可以将此编译器选项添加到每个项目的设置中：

  /warnaserror:1591

【讨论】：

这只会强制他们添加评论。它不会强迫他们添加真正有用或有意义的评论。
永恒的问题。我想您将不得不阅读 cmets 并确定它们的含义和有用性，然后解雇拒绝合作的程序员。这就是他们向团队领导和开发经理支付大笔费用的原因。
其他技术可以包括代码审查（对所有更改或偶尔更改）和指导新团队成员了解良好文档的重要性。或者，编写 SDK 的开发人员充当它的消费者的第一线支持。糟糕的文档可能会导致更多的支持查询，这加强了编写良好、可用文档的重要性。
这听起来像是说服而不是强迫:-)