doxygen

Doxygen是一種開源跨平台的，以類似JavaDoc風格描述的文檔系統，完全支援C、C++、Java、 Objective-C 和IDL語言，部分支援PHP、C#。注釋的文法與Qt-Doc、KDoc和JavaDoc相容。Doxgen可以從一套歸檔 源檔案 開始，生成HTML格式的線上類 浏覽器 ，或離線的LATEX、RTF參考手冊。

Comment Format https://srv1.axissemi.com/trac/axis-cn/wiki/CommonCodingRule#CommentFormat

Please add comment to the function in Head file as following:

/**
* @fn void readme(int a, int b=1)
* describe the function
* @param  a  int, describe this param, range[0,0x7fff].
* @param  b  int, describe this param,range[0,0xffff], the default value is 1.
* @return void
* @attention it does't overload, the a must be bigger than -1. the result is loaded in global parameter c.
* @note example:readme(1, 2)
*/
void readme(int a, int b);

      

it generates the html as the follows:

void readme(int a, 
            int b
           )
describe the function
Parameters:
    a  int, describe this param, range[0,0x7fff].
    b  int, describe this param,range[0,0xffff], the default value is 1.

Returns:
    void

attention:
    it does't overload, the a must be bigger than -1. the result is loaded in global parameter c.

Note:
    example : readme(1, 2)
      

a.define the function's name at the first line in this comment block. the string must be the same as the function's declaration.

b.at the second line , it introduces this function.

c.at the third line, it introduces the parameter, show its range, if it has default value, it has to specify it

d.at the return block, it introduces the return value.

e.at the attention block, it introduces the attentions, it has to show the precautions as follows:

1.whether it overloaded.

2.whether it has illegal inputs

3.whether it take up some memory that has to free.

it is not a complete claim, we will improve it in the future.

d.at the note block, you have to give a example and the result of the this example.

f.the number of the characters has not to be greater than 80 except that the line which specifies the overload function.

if you show the assembly language in this block, please using the format as the coding style show.

if the function is overloaded, you must replace the fn '\overload' with fn, the example is as follows:

the origin function which is not overloaded:
/**
* @fn void readme(int a, int b=1)
* describe the function
* @param  a  int, describe this param, range[0,0x7fff].
* @param  b  int, describe this param,range[0,0xffff], the default value is 1.
* @return void
* @attention it does't overload, the a must be bigger than -1. the result is loaded in global parameter characters.
* @note example:readme(1, 2)
*/
void readme(int a, int b);

the origin function which is overloaded:
/*! *\overload void readme(char a)                   (don't need to divide this line into 80 characters)
* describe the function
* @param  a  char, range[a, A).
* @return void
* @attention it overloaded, the result is loaded in global parameter c.
* @note example:readme('c')
*/
void readme(char a);

      

if you want to change line, please append '\n' after the end of last line.

if you want to insert space into the comment line, please replace '&nbsp' with ' '. the format is as follows：

/**
* @param a  int the input,this funtion\n
* just for test.
* @note def:a=1
* @note       b=2  
*/   
      

the rerules is as follows:

parameters:
            a  int the input,this funtion
               just for test
    note:
          def:a=1
             b=2
      

the more command's description that you may need are in

 Command description

the more detail about special character description that you may refer the html grammar.

please add comment to CPP file as followsing:

/*--------------------------------------------------------------------------------------------*/
        /*Name       : readme                                                                         */
        /*Fuction    : just for example                                                               */
        /*Author     : hren                                                                           */
        /*Parameters :                                                                                */
        /*             a  int, describe this param, range[0,0x7fff].                                  */
        /*             b  int, describe this param,range[0,0xffff], the default value is 1.           */
        /*return     : void                                                                           */
        /*--------------------------------------------------------------------------------------------*/
        void  readme(int a, int b){
            
            //just for single line comment
            ......
        }

      

the comment in CPP file is similar to the head file. using '//' the annotate the single line.

the description of Parameters and return are the same as the head file.the number of the characters has not to be greater than 80 in every line. 

Automatically Generate COMMENT DOC https://srv1.axissemi.com/trac/axis-cn/wiki/CommonCodingRule#AutomaticallyGenerateCOMMENTDOC

1. Type "doxygen -g Doxyfile" to generate the configure file "Doxyfile".
2. Modify the configure file as follows:

   DOXYFILE_ENCODING = UTF-8，預設編碼為UTF-8，這樣可以支援中文。
   
   PROJECT_NAME = "Sil"，項目名稱，多個單詞需要使用引号(“”)。
   
   PROJECT_NUMBER = "1.0 beta"，項目版本号。
   
   OUTPUT_DIRECTORY = doxygen，輸出文檔的目錄，如果為空，表示在目前目錄，建議寫上表示本工程的有意義的目錄名稱。
   
   OUTPUT_LANGUAGE = English，文檔語言，可以指定為Chinese。
   
   IMAGE_PATH = image_dir，指定圖檔存放的目錄，我們将圖檔放到目前目錄下的image_dir目錄中，因為我們的文檔會出現測試圖檔示例。
   
   HTML_OUTPUT= . ，html輸出目錄名稱，預設為html目錄，如果為“.”則表明為上述OUTPUT_DIRECTORY目錄。
   
   GENERATE_LATEX = NO，是否生成LaTeX，預設生成的，但我們不想生成。
   
    好了，我們需要修改的就這麼多，使用上述第2步驟的指令就可以生成一個漂亮的文檔了。此外還有一些常用的設定選項。
   
   INPUT =xxx，代碼檔案或目錄，多個檔案(目錄)需要以空格隔開，如果不指定，表示目前目錄，但是，如果指定目錄且目前目錄有代碼檔案的話，需要使用點号(“.”)表示目前目錄。
   
   FILE_PATTERNS=xxx，指定各種檔案，我們常用為*.cpp *.c *.h，等等。
         

3. type "doxygen ", then the html file were generated under the directory "html".

參考網站：

     http://www.stack.nl/~dimitri/doxygen/docblocks.html

     http://www.stack.nl/~dimitri/doxygen/commands.html