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