• 使用Doxygen生成C#帮助文档


    一. 什么是Doxygen?

    Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
    Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。
    因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。

    二. 准备软件

    2.1 doxygen

    官网:http://www.doxygen.nl/

    下载地址:http://www.stack.nl/~dimitri/doxygen/download.html

    image

    2.2 graphviz

    官网:http://www.graphviz.org/content/dot-dotexe

    注:这个软件不是必需的,如果需要使用更强大的功能比如类继承体系图等则需要安装此软件配置使用,需要安装Java环境
    下载地址:http://www.graphviz.org/Download_windows.php

    image

    2.3 Microsoft HTML Help Workshop

    chm文件制作工具

    三个软件

    三. C#注释

    <Summary> 对整体进行概要性描述
    <summary>Description</summary>
    类、属性(不推荐)、方法等 
     
    <para> 跟在Summary之后,对方法所涉及的入口参数进行有效的解释
    <param name=username>本参数是用户的帐号</param>
    方法的入口参数; 
     
    <returns> 对方法的返回值进行解释;
    <returns>返回值零代表操作成功,-1代表操作不成功</returns>
    方法的返回值; 
     
    <remarks> 对一些语句进行备注性描述
    <remarks>本类需要调用另外一个User类相关方法</remarks>
    类、方法、属性等; 
     
    <see> 在生成的文档中产生一个连接到其它描述的超链接;
    <see cref=”[member]”/>
    可以在其它注释标识符中加入 
     
    <seealso> 与上者的区别是本标识符显示超链接在一个文档的尾部的“See Also”区域,而前者在文档之中;
    <seealso cref=”[member]”/>
    不可以在其它注释标识符中加入 
     
    <value> 对一个属性进行概要性解释;
    <value>这是一个public属性</value>
    属性 
     
    <code> 如果需要置入一部分源代码段,可以使用本标识符将其标记出来
    <code>
    public int add(int a,b)
    {
    return a+b;
    }
    </code>
    可以在其它注释标识符中加入 
     
    <exception> 对程序中可能抛出的异常做解释;
    <exception cref=”System.Exception>抛出的异常情况</exception>
    在方法当中如果有抛出异常,如“try…catch结构”时可以使用本标识符做解释 
     
    <permission> 对方法的访问权限做一些解释:
    <permission cref=”System.Security.PermissionSet>这是公共方法</permission>
    方法,属性 
     
    <c><code>标识符基本相同,但本标识符仅用于单行代码;
    <c>return a+b;</c>
    可以在其它标识符中插入使用; 
     
    <example> 举例说明,通常与<code>配套使用;
    <example> 以下示例说明如何调用Add方法:
    <code>
    class MyClass
    {
    public static int Main()
    {
    return Add(1+2);
    }
    }
    </code>
    </example>
    可以在其它标识符中插入; 
     
    <paramref> 在其它地方引用一个入口参数
    <paramref cref=”a>请注意,这是一个整型参数</paramref> 

    四. 配置

    4.1 Doxygen工作目录

    请选择一个已存在的非中文路径的文件夹,如下图:

    image

    4.2 Wizard 向导

          4.2.1 Project 项目

    image

          4.2.2 Mode 模式

    image

          4.2.3 Output 输出

    将With search function的钩去掉

    image

    plain HTML,为下图一,with navigation panel为下图二

    image   image

          4.2.4 Diagrams 图表

    image

    (Use built-in class diagram generator)将使用内置的生成功能生成每个类的类图,只有一个类是不为生成的。

    如果需要更加大的功能比如类继承体系图请选择第三项(Use dot tool from the GraphViz package)需要安GraphViz。

    4.3 Export 导出

          4.3.1 Project  项目

    OUTPUT_LANGUAGE选择chinese TAB_SIZE是Tab的长度

    image

    image

          4.3.2 Build 构建

    默认是会生成public方法,这里也选择EXTRACT_ALL。它保证输出所有public方法及project方法,EXTRACT_STATIC是生成静态方法。

    image

          4.3.3 Input 输入

    Input为输入目录,支持多个目录,我们可以放入项目目录和include目录,下面的Exclude是忽略目录与文件,可自行添加。

    image

          4.3.4 Index 索引

    选择ALPHABETICAL_INDEX,类中将有一个组合类型索引项。

    image

    生成的索引如下图所示

    image

          4.3.5 HTML

    如果你之前选择了(prepare form compressed HTML(.chm))这里抽GENERATE_HTMLHELP项会是选择状态,它下面的CHM_FILE填写你的CHM文档的名字(要加上.chm)。HHC_LOCATION则选择你的HTML Help WorkShop安装目录下的HHC程序,一般会在C:/Program Files (x86)/HTML Help Workshop/hhc.exe。选择TOC_EXPAND会生成左边的树目录。

    image

          4.3.6 Dot

    如果你选用内置的生成功能(Use build-in class diagram generator)此时CLASS_DIAGRAMS会是选择状态,而HAV_DOT是未选择状态,如果你选择用GraphViz的dot工具生成(Use dot tool from the GraphViz package)情况则相反,请你选择上CLASS_DIAGRAMS。此时你需要设置下面的DOT_PATH为GraphViz的安装目录,否则将无法生成。

    另外以下选项选择则生成对应的图,不选择则不生成。

    CLASS_GRAPHS                   类图

    COLLABORATION_GRAPH      协作图

    GROUP_GRAPHS                   组图

    UML_LOOK                           是否UML外观

    INCLUDE_GRAPH                   include

    INCLUDED BY GRAPH             被include

    CALL_GRAPH                        调用

    CALLER_GRAPH                    被调用

    DIRECTORY_GRAPH               目录图

    GRAPHICAL_HIERARCHY        继承体系图

    image

    五.Run 运行

    配置好后中进入Run选项卡单击 Run Doxygen 即开始生成,等待生成完毕后点击 “Show HTML output

    image

    六.HTML效果图

    image 

    imageimage

    image

    七.CHM效果图

    imageimage

    分享一下我的Doxygen配置文件:http://pan.baidu.com/s/1hqh5Clm

    八.提醒

    提醒一下,如果是WIN8的操作系统,建议设置dot的兼容性,并以管理员身份运行,否则一直会弹出dot停止运行的警告框

    image

  • 相关阅读:
    微信小程序の模板
    微信小程序の条件渲染
    微信小程序のwxml列表渲染
    769. Max Chunks To Make Sorted
    766. Toeplitz Matrix
    747. Largest Number At Least Twice of Others
    746. Min Cost Climbing Stairs
    729. My Calendar I
    724. Find Pivot Index
    718. Maximum Length of Repeated Subarray
  • 原文地址:https://www.cnblogs.com/zhaoqingqing/p/3842236.html
走看看 - 开发者的网上家园