无障碍的 XML 注释答案

【问题标题】：Unobstructive XML commenting无障碍的 XML 注释
【发布时间】：2013-05-15 13:22:49
【问题描述】：

我已经创建了一个项目并开始记录它。 Sandcastle 使用 XML cmets 创建一个很好的帮助文件，但是 XML cmets 使代码几乎不可读。我现在写的每一节课都是这样开始的：

/// <summary>
/// Summary of Foo class
/// </summary>
public class Foo
{
    ///<summary>
    ///Summary of bar</summary>
    public int bar;
    ///<summary>
    ///Summary of bat</summary>
    public String bat;

    ///<summary>
    ///Summary of constructor</summary
    ///<param name="a">description of a</param>
    ///<param name="b">description of b</param>
    public Foo(int a, int b)
    ....
}

有什么方法可以清理这段代码，同时留下足够的信息来创建一个很好的帮助文件？

【问题讨论】：

标签： c# .net xml sandcastle

【解决方案1】：

如果您不确定，可以在这里查看... http://msdn.microsoft.com/en-us/library/b2s063f7.aspx

这是他们的例子： http://msdn.microsoft.com/en-us/library/aa288481(v=vs.71).aspx

但老实说，这正是它应该看起来的样子。除非我对其进行更改，否则我通常会尽量减少所有内容。但是，如果新开发人员加入您的项目，那么完整的 XML 文档可能是天赐之物。

只要克服它并希望学会爱它吗？

【讨论】：

这太糟糕了，因为我的一些方法有超过 10 个参数，所以你可以想象它的样子。基本上整个屏幕由 cmets 接管，而阅读代码的人不需要。
这就是为什么它们都是可折叠的。写下来，崩溃，继续。如果您需要进行更改，请扩展并执行此操作。我永远不会让所有 cmets 打开，文件就像你说的“不可读”。 ctrl-M-O（全部折叠）是你的朋友！老实说，当我开始使用它时，我也有同样的感觉，让一切都变得如此臃肿。现在，如果没有 XML，我什么都不会留下，而 sandcastle 可以很好地生成文档。
我期待着 IDE 能够为我们很好地格式化这一切的那一天（当然，我们并没有主动编辑它）。与此同时，我实际上已经阅读了很多，我并没有真正注意到它的格式。
@HH 有 10 个参数有点多，问题可能是缺乏重构而不是 XML 文档:)
@Wrightboy，沙堡文档很棒，没有争论。我遇到的问题是，将来我可能不是唯一编辑此代码的人，而且我不想假设他们可能正在使用的 IDE。（虽然我认为可折叠的 cmets 很标准）。

【解决方案2】：

有一个扩展^*：

Hide/Show Comments

^{*_{我自己没有尝试过，但它看起来可能对你有帮助。}}

【讨论】：

【解决方案3】：

include tag 允许您将大部分文档放在单独的文件中。通常，这用于在虚拟或接口成员的各种实现中重用通用文档，但它也可以用于简单地分离出文档。

【讨论】：