使用Doxygen生成net幫助文檔

一． 什麼是Doxygen?
Doxygen 是一個程序的文件產生工具，可將程序中的特定批註轉換成爲說明文件。一般咱們在寫程序時，或多或少都會寫上批註，可是對於其它人而言，要直接探索程序裏的批註，與打撈鐵達尼號一樣的辛苦。大部分有用的批註都是屬於針對函式，類別等等的說明。因此，若是能依據程序自己的結構，將批註通過處理從新整理成爲一個純粹的參考手冊，對於後面利用您的程序代碼的人而言將會減小許多的負擔。不過，反過來講，整理文件的工做對於您來講，就是沉重的負擔。
Doxygen 就是在您寫批註時，稍微按照一些它所制訂的規則。接着，他就能夠幫您產生出漂亮的文檔了。
所以，Doxygen 的使用可分爲兩大部分。首先是特定格式的批註撰寫，第二即是利用Doxygen的工具來產生文檔。

二． 下載地址
doxygen-1.8.4-setup.exe
http://jaist.dl.sourceforge.net/project/doxygen/rel-1.8.4/doxygen-1.8.4-setup.exe
graphviz-2.30.1.msi(不是必需)若是須要使用更強大的功能好比類繼承體系圖等則須要安裝此軟件配置使用
http://www.graphviz.org/pub/graphviz/stable/windows/graphviz-2.30.1.msi

三． 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>

四． 配置
Step 1:是Doxygen的工做目錄，請指定一個已存在的非中文的文件夾
主界面以下圖：

Step 2:具體配置

Wizard選項卡

       Project

 

Mode

 

Output

將With search function的鉤去掉

 

Diagrams

(Use built-in class diagram generator)將使用內置的生成功能生成每一個類的類圖，只有一個類是不爲生成的。

若是須要更加大的功能好比類繼承體系圖請選擇第三項(Use dot tool from the GraphViz package)須要安GraphViz。

 

Export選項卡

Project 

OUTPUT_LANGUAGE選擇chinese

TAB_SIZE是Tab的長度

 

Build

默認是會生成public方法，這裏也選擇EXTRACT_ALL。它保證輸出全部public方法及project方法，EXTRACT_STATIC是生成靜態方法。

 

Input

Input爲輸入目錄，支持多個目錄，咱們能夠放入項目目錄和include目錄，下面的Exclude是忽略目錄與文件，可自行添加。

 

Index

選擇ALPHABETICAL_INDEX，類中將有一個組合類型索引項。

 

生成的索引

HTML

若是你以前選擇了(prepare form compressed HTML(.chm))這裏抽GENERATE_HTMLHELP項會是選擇狀態，它下面的CHM_FILE填寫你的CHM文檔的名字。HHC_LOCATION則選擇你的HTML Help WorkShop安裝目錄下的HHC程序，通常會在C:/Program Files (x86)/HTML Help Workshop/hhc.exe。選擇TOC_EXPAND會生成左邊的樹目錄。

 

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        繼承體系圖

配置好後中進入Run選項卡單擊Run Doxygen即開始生成。

生成完畢後

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace DoxygenTest
{
    public class Test
    {
        /// <summary>
        /// 這個是爲了測試生成的文檔
        /// </summary>
        /// <example>
        ///     <code>
        ///         Test.DoxygenTest("測試",1000);
        ///     </code>
        /// </example>
        /// <param name="str">參數1是字符串</param>
        /// <param name="int1">這個是整型</param>
        /// <returns>返回空串</returns>
        public static string DoxygenTest(string str, int int1)
        {
            return string.Empty;
        }
    }
}

程序代碼

 配置文件下載地址