c# 利用注释summary生成文档

深碍√TFBOYSˉ_ 2022-07-12 00:00 273阅读 0赞

# c\# 利用注释summary生成文档 #

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

## 注释写法 ##

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

/// <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特性可参见][cref]

## 关于第三方工具生成文档的可以参见 ##

1 [ Sandcastle Help File Builder][Sandcastle Help File Builder]

下面是一个生成的文档的例子，如图：

![Center][]

2 [ swagger-ui ][swagger-ui]

swagger 更适合生成restful风格api的文档，而且可以直接在页面上测试这个接口。

\--- end ---

[cref]: https://msdn.microsoft.com/zh-cn/library/cc837134
[Sandcastle Help File Builder]: http://blog.csdn.net/huwei2003/article/details/42028163?locationNum=2&fps=1
[Center]: /images/20220711/bb4b780a291a47dc93566a7c0cdb8627.png
[swagger-ui]: http://blog.csdn.net/huwei2003/article/details/50501977?locationNum=1&fps=1