Integration of Doxygen tools in VS2103 environments

I have been learning two or three times, almost this time to summarize:

Doxygen is an open-source, cross-platform, document system that is described in a similar Javadoc style, fully supported in C, C + +, Java, objective-c, and IDL languages, partially supported by PHP, C #. The syntax for annotations is compatible with Qt-doc, KDOC, and Javadoc. Doxgen can start with a set of archive source files, generate an HTML-formatted online class browser, or an offline latex, RTF reference manual.

Doxygen is a program's file generation tool that converts specific annotations in a program into a description file. Usually we write the program, more or less will be written in the comments, but for others, to directly explore the program in the comments, and salvage titanic the same hard. Most useful annotations are for descriptions of functions, categories, and so on. Therefore, if you can follow the structure of the program itself, the annotations are processed and re-organized into a purely reference manual, for those who use your program code later will reduce a lot of burden. However, in turn, the work of filing is a heavy burden for you. Doxygen is when you write a comment, slightly following some of the rules it has set. Then, he can help you produce beautiful documents. Therefore, the use of Doxygen can be divided into two parts. The first is the writing of annotations in a particular format, and the second is the use of Doxygen tools to produce documents.

Reference posts are: http://sunzhennian.blog.163.com/blog/static/1951730712011112210184592/

http://blog.csdn.net/flatcd/article/details/138678

http://blog.csdn.net/u012501459/article/details/37668893

http://blog.csdn.net/bigpudding24/article/details/45247357

Each has the point, oneself in summary.

Use steps

1, the first time use needs to install Doxygen program

2. Generate Doxygen configuration file

3. When encoding, write comments in a format
4. Generate the corresponding document

1, installation Doxygen and related procedures

1.1Doxygen Downloads

HTTP://SOURCEFORGE.NET/PROJECTS/DOXYGEN/?SOURCE=DLP for download

This article uses the Doxygen 1.8.3.1

Installation, we will use the GUI version of Doxywizard,doxygen at the time of configuration.

1.2HTML Help Workshop download

If you want your doxygen to automatically generate a CHM, download the HTML Help Workshop and we will use the Hcc.exe file and the associated DLL

http://www.microsoft.com/en-us/download/details.aspx?id=21138 for download

Download the Htmlhelp.exe and install, remember the installation directory, we will use when the Doxygen configuration.

1.3 Graphviz

Graphviz is an open source toolkit that is launched by the AT and T Labs and is used to draw graphics for the dot language script description. Doxygen uses Graphviz to automatically generate a call graph between classes and between files, such that the toolkit is not installed without this functionality.

Install and record the installation directory, also we need to configure Doxygen

The specific function is the following: including how to produce Doxygen

First download Doxygen on the Internet ,HTML help Workshop. These two softwares are downloaded directly on their respective official websites.

Then use Doxywizard.exe to generate a Doxygen file. Click "D:\program files\doxygen\doxygen\bin\doxywizard.exe" appears the following interface: In the Wizard property page main need to change a place, click on the left "Output" Remove the hook from the Latex in the checkbox on the right, and then specify the working directory of the Doxygen in the STEP1: below, which is the path to the file that the wizard generates.

In the "Wizard" and "Export" There are many parameters that can be edited, temporarily do not modify, and later familiar with the change. Then click "Run Doxygen" under "Run" to generate the script.

Then click "Save as" in the "File" menu to generate the script we need to name the generated script Default.doxygen

Default.doxygen is an ordinary text file, where it is necessary to do some editing, these need to edit the main place is the problem of character encoding, in fact, in the previous graphical interface can also be changed.

The main areas to be modified are the following:

Generate_htmlhelp = YES

Output_language = Chinese

chm_index_encoding = gb2312

doxyfile_encoding=gb2312

input_encoding=gb2312

Then the Default.doxygen will be dealt with.

The next step is to integrate these tools into vs to make it easier to use them later. Copy the Default.doxygen to the project under which you want to generate the document

1. Integrated Doxygen

In the vs Environment:tools->external tools->add

Title: Doxygen

Command: D:\Program files\doxygen\bin\doxygen.exe (installation directory for Doxygen)

Arguments: $ (projectdir) \default.doxygen

Initial directory: $ (projectdir)

(You can tick the Use Output window check box)

Clicking Tools->doxygen will generate an HTML folder in the project directory, which is an automatically generated comment file.

2. Integrated CHM Authoring tool HTML help Workshop

Install HTML help Workshop first.

In the vs Environment:tools->external tools->add

Title: HTML help Workshop

Command: D:\program files\doxygen\htmlhelp\hhw.exe (installation directory for HHW)

Arguments: $ (projectdir) html\index.hhp

Initial directory: $ (projectdir)

Click tools->html Help Workshop, will appear hhw form, compile, can get index.chm file.

Note: When compiling, a window will be called to confirm the pathname, and vs automatically pass in the path name is wrong, 2 double quotation marks, minus the double quotation marks, compile, you can succeed. such as:

3. Integrated CHM file viewing tool hh.exe

In the vs Environment:tools->external tools->add

Title: viewchm

Command: C:\WINDOWS\hh.exe (WINDOWS comes with)

Arguments: $ (projectdir) Html\index.chm

Initial directory:

Click tools-> viewchm and you will see the Index.chm file.

If only HTML comments, you should not install the two behind!

2. Configure Doxygen

2.1 Basic Configuration

In the basic configuration, we will introduce some basic configuration about Doxygen, such as various garbled characters, output content and so on.

First we open the start-"All Programs-" doxygen-"Doxywizard

First, select your working directory (config file location D:\Doxygen) and click Select.

The second step is to configure

wizard Tab:

First modify project name, select the directory where the source code is scanned, and then click Scan Recursively (recursive scan) to select the output directory to view as the Test selection desktop.

Under the wizard's Topics mode, select all entities, you can output a relatively complete function, whether it contains the source code to see your own situation, choose your language below. The author here is using C # so choose Java or C #

In output, if you need to export the CHM format, please tick.

Choose to use the Graphviz package in diagrams to export the UML

Expert tab:

Description: Encoding format, UTF-8 is preferred. Select GB2312 if you want to display Chinese.

Tab_size is mainly to help file the indentation size of the code, such as @code and @endcode section of the code layout, the proposed set to 4.

Build page, which is the more critical configuration page in the build Help information:

Extract_all: All functions are output, but the private and static functions do not belong to their control.

Extract_private: Outputs the PRIVATE function.

Extract_static: The output STATIC function. There are also several extract to view the document accordingly.

Show_include_files Indicates whether the include file is displayed, and if it is on, a page is specifically generated in the help that contains all the columns containing the file

Table.

Inline_info: If enabled, in the Help document, an inline modifier is indicated in front of the inline function.

Sort_member_docs: If enabled, the function names will be sorted when the list of help documents is displayed, otherwise in the Order of interpretation

Shown

Description: Input_encoding (the encoding of the input source file) to be the same as the encoding format of the source file. If the source file is not UTF-8 encoded it's best to turn around.

Summary: I check to see that my code file is utf-8 (open file in vs2013 Select Save As to see the encoding format) ((VS2012 words): File, advanced save option).

In expert HTML, the first thing to do is to look at the hhc_location option and add the installation directory (note: The author directory is C:/Program Files (x86)/html help Workshop/hhc.exe)

Tick chm_index_encoding, the character set in your source code is what you fill out,

Then tick class_diagrams,uml_look in the expert dot

To reduce the CHM volume, select GIF or JPG in the Dot_image_format.

Finally, select the position of the output of the good dot_path.

Click the Run doxygen button and Doxygen will fetch the code from the source to generate the document in your custom format. Several errors:

Error:when enabling Generate_htmlhelp the search engine (searchengine) should be disabled. I ' ll do it for you.

Warning:the selected output Language "Chinese" have not been updated

Since release 1.8.2. As a result some sentences may appear in 中文版.

FIX: Set the searchengine in HTML to No

The next job is to learn Doxygen's annotated specifications, and refer to the Doxygen QuickStart, section 2nd, "Common annotation syntax." Slowly you can experience the convenience of Doxygen.

3, Doxygen of the annotation specification

Not all annotations in the program code will be handled by Doxygen. You must write according to the correct format. In principle, Doxygen only handles annotations related to the structure of the program, such as
Function,class, file annotations and so on. The annotation inside the function is not processed. Doxygen can handle several types of annotations.

Javadoc Type:

/**
* ... Comments...
*/

QT Type:

/*!
* ... Comments...
*/

Single-line type of annotation:

/// ... Comments...

Or

//! ... Comments...

Which type of pattern to use completely depends on your preferences. To the author, I will use the Javadoc type for a wide range of annotations. The single-line annotation uses the type of "//".

Additionally, because Doxygen is considered an annotation, the program code is later interpreted. That is, any annotation is a program code after the description. If you want to annotate the previous thread
Code, you need the notation in the format below.

/*!< ... Comments ... */
/**< ... Comments ... */
!< ... Comments...
< ... Comments...

The above method does not apply anywhere and can only be used in class member or function parameters.

For example, if we have the following class.
Class MyClass {
Public
int member1;
int Member2:
void Member_function ();
};

When you add a comment, it becomes like this:

/**
* My Custom Category description ...
*/
Class MyClass {
Public
int member1; < First member Description ...
int Member2:///< Second member description ...
int member_function (int a, int b);
};

/**
* Member_funtion Description of the custom category ...
*
* @param the description of a parameter a
* Description of @param b parameter B
*
* @return returned to A+b.
*/
int myclass::member_function (int a, int b)
{
return a+b;
}

When you use Doxygen to generate the documentation, Doxygen will help you parsing your code. and the corresponding files are established according to the program structure. Then put your annotations in the right place, based on their location. You may have noticed that in addition to the general text descriptions, there are other special instructions, such as @param and @return. This is another important part of Doxygen, because a category or function actually has a few parts to describe. In order for Doxygen to be able to judge, all of us must use these instructions to tell Doxygen that the annotations behind them are explaining something. Doxygen will help you with these parts for special handling or typesetting. Even make reference links.
First, let's start by explaining a specific format for a category or function annotation in Doxygen.
/**
* Simple description of class or function ...
*
* Detailed description of class or function ...
* ...
*/
The above example says that when Doxygen handles a class or function annotation, it first judges the first behavior as a simple explanation. This simple description will always appear to the empty line. Or meet the first "." So far. Subsequent annotations will be treated as a detailed description. The difference between the two is that doxygen in some places will only display simple instructions, not detailed instructions. such as: A list of class or function.

Another clear way is to specify @brief directives. This will clearly tell Doxygen, which is the simple explanation. For example:
/**
* Simple description of @brief class or function ...
*
* Detailed description of class or function ...
* ...
*/

In addition to this class and function, Doxygen can also be described for the file, provided that the annotation needs to be placed in front of the file. The main use of some directives, usually this part of the note will be placed in the beginning of the file place. Such as:

/*! \file myfile.h
Simple description of \brief file

Detailed description.

\author Author Information
*/

As you can see, the file annotations in the approximate format, please do not be confused by "\". In fact, "\" and "@" are the same, are told Doxygen behind is an instruction. Both can be used in Doxygen. I prefer to use "@" myself.
Then we will explain some of the commonly used directives:

@file	Description of the file's annotations.
@author	Author's information
@brief	Used for class or function annotations, followed by a simple description of class or function.
@param	Format is @param arg_name Parameter Description Used primarily for function descriptions, followed by the name of the parameter, and then followed by a description of the parameter.
@return	The following function returns a description of the value. The annotation used for the function. Describes the return value of the function.
@retval	Format is @retval Value Returns a description Used primarily in function descriptions to illustrate the meaning of specific return values. So we have to go back to the value first. Then put the description of the return value.

Doxygen supports a lot of instructions, some even about the output layout control. You can find detailed instructions in the instructions for using Doxygen.

Below we prepare a set of example.h and Example.cpp to illustrate how Doxygen annotations are used:

Example.h:

/**
* @file the Include file for this example.
*
* This file only defines the class example.
*
* @author [email protected]
*/

#define EXAMPLE_OK 0///< defines the EXAMPLE_OK macro as 0.

/**
* Simple description of @brief Example class
*
* This example illustrates example class.
* This is a very simple example.
*
*/
Class Example {
Private
int var1; < It's a private variable.
Public
int var2; < This is a variable member of public.
int var3; < This is another variable member of public.
void ExFunc1 (void);
int ExFunc2 (int A, char b);
Char *exfunc3 (char *c);
};


Example.cpp:

/**
* @file The program code file for this example.
*
* This file is used to define the example of this class.
* member function.
*
* @author [email protected]
*/

/**
* Simple description of @brief ExFunc1
*
* EXFUNC1 does not have any parameters and returns values.
*/
void Example::exfunc1 (void)
{
Empty funcion.
}

/**
* Simple description of @brief EXFUNC2
*
* EXFUNC3 () returns the added value of two parameters.
*
* @param A to add the parameters.
* @param b is used to add parameters.
* @return Returns the result of adding two parameters.
*/
int ExFunc2 (int A, char b)
{
return (A+B);
}

/**
* Simple description of @brief ExFunc3
*
* EXFUNC3 () returns only the indicator entered by the parameter.
*
* @param c passed in the character pointer.
* @retval null empty string.
* @retval! Null non-empty string.
*/
char * EXFUNC2 (char * c)
{
return C;
}

Integration of Doxygen tools in VS2103 environments