c# 利用注释summary生成文档

c# 利用注释summary生成文档

在写代码的过程中养成良好的注释习惯是非常必要的，这也为生成代码的说明文档打下了基础。再利用文档生成工具可以生成标准的文档，省时省力。

 

 

注释写法

在一个方法写好后，在方法名上一行直接输入"///"回车即可生成方法说明的主体结构，只需对方法名，用途，参数加以说明。类说明写法也一样

一个方法的注释例子：

 

 

 

/// 

/// 按页面分类取轮播列表;
/// result List-DtoBanner;
/// not require login;
/// 
/// 接口响应
/// 父id
/// DtoBanner
///  
/// DtoBanner see 
/// 
public static DtoBanner ListByType(AppCall call, int parentId)
{
	// code remove
	return null;
}

以下是一个msdn上的例子：

 

/// 

        /// This sample shows how to specify the  constructor as a cref attribute.
        /// 
        public TestClass(int value)
        { }

        /// 

        /// The GetZero method.
        /// 
        ///  
        /// This sample shows how to call the  method.
        /// 
        /// class TestClass 
        /// {
        ///     static int Main() 
        ///     {
        ///         return GetZero();
        ///     }
        /// }
        /// 
        /// 
        public static int GetZero()
        {
            return 0;
        }

 

 

 

说明：

summary 部分是对方法或类的说明，一般只有public,protected类型的方法才有必要加;

标记的文本是唯一有关 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 ---