C program document generator introduction (DOXYGEN)
Program documentation, once a programmer's headache problem. Write a program document, spend time, but it is not very difficult; how trouble is the program documentation, the program document should be updated with the synchronous update, otherwise the documentation and program will be detached, the document will become a useless thing. Fortunately, there are many well-used document generators to solve this problem. Currently popular C document generators are doxygen. This article briefly introduces Doxygen's document annotation method for beginners reference: C program document generator introduction (Doxygen) Mu Feng Net
1. Modular definition (one page separately)
/ * * @Defgroup module name module description text
* @ {
* /
... defined content ...
/ ** @} * / // module end
2. Group definition (group display in one page)
/ * @Name group description text
* @ {
* /
... defined content ...
/ ** @} * /
3. Data, macro definition, type definition brief description
/ ** Brief Description Text * /
#define float float
/ ** @brief brief description text (in front plus @Brief is a standard format) * /
#define min_uint 0
/ * * Branch brief description / N
* This is a brief description of the second line
* /
INT B;
4. Function Description
/ * * Summary function description text
* @Param [in] param1 parameter 1 Description
* @Param [OUT] PARAM2 parameter 2 Description
* @Return return value description
* /
Int Func (int Param1, int param2);
/ * * Open file / n
* After the file is opened, you must use the :: closefile function to close.
* @Param [in] file_name file name string
* @Param [in] file_mode file opens the mode string, can be combined by the following modules:
* - R reading
* - w can be written
* - a Add
* - T text mode (cannot be used with B)
* - B binary mode (cannot be used with T)
* @Return returns the file number
* - -1 indicates that the file failed
* @Note file After the file is opened, you must use :: closefile function to close
* @PAR example:
* @Code
// Open the file with text read only mode
INT f = OpenFile ("D: //Test.txt", "RT");
* @Endcode
* @See :: readfile :: Writefile :: Closefile
* @DepRecated Due to special reasons, this function may be canceled in future versions.
* /
INT OpenFile (const char * file_mode);
5. Enumeration Type Definition
/ ** enumeration constant * /
Typedef Enum TDAYOFWEEK
{
SUN = 0,
/ ** "Sunday (note," <"小 小 于 开 start) * /
MON = 1,
/ **: Monday * /
Tue = 2,
/ ** WED = 3, / ** THU = 4, / ** FRI = 5, / ** / ** } / ** Define Type TenumDayofweek * / Tenumdayofweek; 6. Project symbol tag / * * A list of events: * - mouse events * - # mouse move evenet * - # mouse click event / n * more info it the click event. * - # Mouse Double Click Event * - KEYBOARD Events * - # key down Event * - # key up Event * * more text here. * / The result is: A List of events: Mouse Events Mouse Move Event Mouse Click Eventmore Info About The Click Event. Mouse Double Click Event Keyboard Events Key Down Event Key Up Event More text here. Code demonstration: / ** / / * @ DFGroup Examples Auto Note Document Example * @author Mu Feng * @version 1.0 * @ d @ @ / / ** / / * @Name file name constant * @ {* / / ** / / ** Log file name * / #define Log_FileName "D: //log//debug.log" / ** / / ** Data file name * / #define Data_filename "D: //data//detail.dat" / ** / / ** Archive file name * / #define Bak_filename "D: //data//backup.dat" / ** / / ** @} * / // File name constant / ** / / * @Name system status constant * @ {* / / ** / /** normal status */ #define SYS_NORMAL 0 / ** / / ** Fault status * / #define SYS_FAULT 1 / ** / / ** Warning status * / #define SYS_WARNNING 2 / ** / / ** @} * / // System state constant / ** / / ** enumeration constant * / Typedef ENUM TDAYOFWEEK {Sun = 0, / ** // ** / ** / / ** Define Type TenumDayofweek * / Tenumdayofweek; / ** / / ** Define type penumdayofweek * / Typedef Tenumdayofweek * Penumdayofweek; / ** / / ** Define enumeration variables ENUM1 * / Tenumdayofweek enum1; / ** / / ** Define enumeration pointer variables enum2 * / Penumdayofweek p_enum2; / ** / / * @Defgroup fileutils file operation function * @ {* / / ** / / * * Open the file / n * file After the file is successfully opened, you must use the :: closefile function to close. * @Param [in] file_name file name string * @Param [in] file_mode file open mode string, can be combined by the following modules: * - r Read * - W can be written * - a Add * - T text mode (cannot be used with B) * - b binary mode (cannot be used with T connections) * @return return file number * - -1 indicates that the open file failed * @note file After opening success, you must use: closefile function Close * @PAR example: * @code // Open file INT f = OpenFile ("D: //test.txt", "RT"); * @endcode * @see :: readfile :: writefile :: closefile * @DepRecated Due to special reasons, this function may be canceled in the future version. * / int Openfile Const charr * FILE_NAME, Const charr * File_mode); / ** / / * * Read file * @Param [in] File file number, see ::: OpenFile * @Param [out] buffer for storing the read file content * @Param [in] LEN needs to read the file length * @RETURN Returns the length of the read file * - -1 Represents the reading file failed * @pre / e file variable must be used: OpenFile return value * @pre / e buffer can't be null * @see :: OpenFile :: Writefile: : Closefile * / int Readfile int File, charr * Buffer, int Len; / ** / / * * Write file * @Param [in] File file number, see ::: OpenFile * @Param [in] buffer is used to write file content to be written * @Param [in] LEN needs to write file length * @RETURN Returns the length of the write * - -1 Represents write file failed * @pre / e file variable must be used: OpenFile return value * @see :: OpenFile :: readfile :: closefile * / int Writefile int File, Const charr * Buffer, int Len; / ** / / * * Close the file * @Param file file number, see :: OpenFile * @retval 0 for success * @retval -1 indicate failed * @see :: OpenFile :: Writefile :: readfile * @Deprecated Due to special reasons, This function may be canceled in future versions. * / int Closefile int File); / ** / / ** @} * / // File operation function / ** / / ** @} * / / / Automatically comment document example Http://ly4cn.cnblogs.com/archive/2005/11/23/282637.aspx http://sourceforge.net/projects/doxygen/ http://www.stack.nl/~dimitri/doxygen/
