[程式設計] 為你的程式自動產生說明文件 -- Doxygen

 

Java 程式語言可以在程式中加入說明文件. 你可以將程式中的說明. 利用指令產生說明手冊. C# 程式語言, 也有類似的功能. 但唯獨 C++ 沒有.

如果你的專案橫跨 Java, C#, C++, 要產生一致性的說明書(PDF, Html). 會是一件讓人頭痛的事.

 

Doxygen, 可以為所有的程式, 撰寫統一的說明格式.

數學公式: 你放心, Doxygen 支援 LaTex.

你寫這樣

\f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$

會變成這樣:

 

 

如何產生文件? [doxygen] -> [doxywizard]

    

加入 method 的說明

-------------------------

/**
     Resize the display dimension.
     @param rec the specified rectangle for displaying
     @return true if the RenderObjectID has already been managed; false otherwise
     <p>
     <b>Example</b><br/>
     <p>
     <pre>
       IPCamera cam=CameraArray[i];
       if(cam!=null){
            java.awt.Rectangle rec= myFrame.PanelArray[i].getBounds();
            cam.resize(rec);
       }
     </pre>
     </p>
     </p>
*/

-------------------------

結果如下:

 

 

 

加入 class 的說明

-------------------------
// 類別的說明
/**
* IPCamera
* 一句話說明 a camera obecjt used to connet IP camera and retrive the video stream.
* <p>
* <b>Usage:</b><br>
*<pre>
*     Step 1: Creating a camera instance
*         IPCamera myCamera=new IPCamera(0,"192.168.0.140",8841,0,"xxx","0000");
*
*     Step 2: Connect the remote camera for retriving video stream
*         myCamera.connect();
*
*     Step 3: Rendering the video stream
*         myCamera.render(JFrameobj,JPannelObj);
*</pre>
*</p>
*/
public class IPCamera {
};

// 方法的說明
/**
    Step 3: Render the video stream
    @param frame the window contain the display panel
    @param myPanel the panel that you want to display the video stream.
*/
void render(Frame frame,Panel myPanel){
}

-------------------------

 

加入自動編號規則

-------------------------

/***  自動編號範例
*    - 第一項目
*         -# 事項 1
*         -# 事項 2\n
*            事項 2 的說明.
*         -# 事項 3  
*    - 第二項目
*         -# 事項 1
*         -# 事項 2
**  更多的說明.*/

-------------------------

 

其他說明範例

-------------------------

/*! /f abc.cpp

    類別的一般說明

    範例 1: 連結到建構子的方式 #Test 或 Test()
    範例 2: 解構子 #~Test 或 ~Test()
    範例 3: 連結到這個類別的 method: member()
    範例 4: 更多的 overload methods: member(int) 和 member(int,int)
    範例5:  連結到 這個類別的變數:#var
    範例 6: 連結到檔案,
         例如: 想要成功編譯這個類別, 請連結 abc.cpp

    範例 7: see also

    \sa Inside a see also section any word is checked, so EType, Val1, GVal1, ~Test and member will be

        replaced by links in HTML.
*/

-------------------------

 

 

by Jing.

 

參考資料:
http://www.stack.nl/~dimitri/doxygen/autolink.html
http://www.powmo.com/ae.html  非常詳盡的 html 教學 (javadoc 支援 html 格式)