在写代码的过程中养成良好的注释习惯是非常必要的，这也为生成代码的说明文档打下了基础。再利用文档生成工具可以生成标准的文档，省时省力。
在一个方法写好后，在方法名上一行直接输入"///"回车即可生成方法说明的主体结构，只需对方法名，用途，参数加以说明。类说明写法也一样 一个方法的注释例子：
/// <summary> /// 按页面分类取轮播列表; /// result List-DtoBanner; /// not require login; /// </summary> /// <param name="call">接口响应</param> /// <param name="parentId">父id</param> /// <returns>DtoBanner</returns> /// <remarks> /// DtoBanner see <see cref="Lb.Model.Dto.DtoBanner"/> /// </remarks> public static DtoBanner ListByType(AppCall call, int parentId) { // code remove return null; }
以下是一个msdn上的例子：
/// <summary> /// This sample shows how to specify the <see cref="TestClass(int)"/> constructor as a cref attribute. /// </summary> public TestClass(int value) { } /// <summary> /// The GetZero method. /// </summary> /// <example> /// This sample shows how to call the <see cref="GetZero"/> method. /// <code> /// class TestClass /// { /// static int Main() /// { /// return GetZero(); /// } /// } /// </code> /// </example> public static int GetZero() { return 0; }
summary 部分是对方法或类的说明，一般只有public,protected类型的方法才有必要加; <summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源，它也显示在 Object Browser Window 中，使用 /doc 进行编译可以将文档注释处理到文件中。 若要基于编译器生成的文件创建最终文档，可以创建一个自定义工具，也可以使用 Sandcastle等工具。
param 是参数部分 returns 是返回值，没有返回值的没有这个 remarks 一般是附加说明，自成生成的结构里没有，可以手动加在后面，
see cref 相当于参考一个引用的其它类或方法，用法同see also，其中cref里的如果引用的其它地方的方法或类，要带上全路径，如果用Sandcastle Help File Builder来生成文档时，这个引用的类也应该在生成文档的范围，否则无法跳转,msdn的部分描述如下： XML 文档标记中的 cref 特性表示“代码引用”。它指定标记的内部文本是代码元素，如类型、方法或属性。 诸如 Sandcastle 这样的文档工具使用 cref 特性，自动生成指向所记录类型或成员的页面的超链接。
cref特性可参见
1 Sandcastle Help File Builder
下面是一个生成的文档的例子，如图：
2 swagger-ui
swagger 更适合生成restful风格api的文档，而且可以直接在页面上测试这个接口。
--- end ---
