Use doxygen to generate Chinese documents for C/C ++ programs (I)

Use doxygen to generate Chinese documents for C/C ++ programs (I)

Annotate the source code according to the agreed format, and use a tool to process the annotated source code to generate a document. Generating documents in this way has at least the following benefits:

• This facilitates code and document synchronization.
• You can manage versions of documents.

Many programming languages have similar document tools, such as javadoc for Java and rdoc for Ruby. For C/C ++ programs, we can use doxygen to generate documents. This article introduces how to use doxygen on Windows platform by setting up a document for the c ++ program "who raises fish.

Doxygen is suitable for API interface documentation, and CHM is a common format for this type of documentation. The latest version of doxygen (currently 1.5.2) unified use of UTF-8 as the output file encoding format, but Microsoft's CHM compilation tool does not support UTF-8, which brings trouble to the production of Chinese CHM documents. This article proposes a solution to this problem.

1 doxygen Introduction 1.1 what to do

Using doxygen to generate documents involves two main tasks:

1. Write a configuration file (doxyfile ). Generally, it is generated using doxywizard and then manually modified.
2. According to doxygen, the code is "documented ".

Then run the following command:

doxygen Doxyfile

You can. The input file, output directory, and parameters are all configured in doxyfile.

1.2 What to get

Doxygen output formats include HTML, latex, and RTF:

• When doxygen outputs HTML documents, it can automatically prepare project files (. HHP), directory files (. HHC), and index files (. HHK) for CHM production ). Use the chmcompiler (hhc.exe) in HTML Help workshopto compile and generate a CHM File.
• Doxygen has prepared makefile for conversion to PDF format while outputting latex documents. As long as the system has installed the appropriate Tex tool, you can generate PDF documents from latex documents.
• The RTF format output by doxygen has been optimized for word and can be converted to Word documents.

1.3 What is needed

The following tools are required to complete the example in this article:

1. The latest version of doxygen can be downloaded from the website of doxygen.
2. Graphviz is a graphical visualization software. Doxygen uses graphviz to generate various graphs, such as the class inheritance relationship diagram, cooperation diagram, and header file containing the relationship diagram. You can download the latest version of graphviz from the graphviz website. Doxygen uses the Layout Engine dot of graphviz, so it is called dot in the document.
3. To solve the Chinese problem, cygwin's iconv program must be used for encoding conversion.
4. To solve the Chinese problem, a command line search and replacement tool is required. I chose the tools fr created by poplar.

You can download these tools from my home http://www.fmddlmyy.cn: doxygen 1.5.2, graphviz 2.12, iconv (GNU libiconv 1.9), and FR 2.1.1.120.

2. Chinese chm format problems

Previously said: currently, the doxygen utf-utf-8as the output file format, but the Microsoft chmcompilation tool (hhc.exe) does not support UTF-8. If hhc.exe is used directly for compilation, Chinese characters cannot be correctly displayed. The solution is simple:

• Compile.

Iconv can be used to encode and convert files. For HTML files, in addition to encoding and conversion of file content

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

Replace UTF-8 with gb2312 in ".

2.1 simplify operations with Batch Processing

I wrote some batch processing files (. BAT) to simplify the processing process, including:

2.1.1 clean. bat -- clear previous output

@ Echo off
Echo clears previous output
If exist refman. chm del/f/Q refman. CHM
If exist output/html del/f/Q output/html /*.*
If exist output/latex del/f/Q output/latex /*.*
If exist output/RTF del/f/Q output/RTF /*.*
If exist output del/f/Q output /*.*


2.1.2 build. bat -- call doxygen to generate the document

@ Echo off
Echo generate document
Doxygen doxyfile


2.1.3 utf82gbk. bat -- convert a specified file (supporting wildcards) from UTF-8 encoding to GBK Encoding

@ Echo off
Echo converts % 1 from UTF-8 encoding to GBK Encoding
For % F in (% 1) do copy % F. utf8
For % F in (% 1) Do iconv-C-F UTF-8-t gbk % F. utf8> % F


This batch file requires that the system has iconv.exe on the top of the page. When iconv is executed, the-C parameter is used to ignore characters that cannot be converted. Otherwise, if the input file contains characters that cannot be converted, the conversion will fail. The input file is backed up to a file with the suffix. utf8.

2.1.4 html-utf82gbk.bat -- converts a specified HTML file (supporting wildcards) from UTF-8 encoding to GBK Encoding

@ Echo off
Call utf82gbk % 1
Echo changed charset in % 1 from UTF-8 to gb2312
Fr % 1-F: charset = UTF-8-T: charset = gb2312


This batch file requires that iconv.exeand Bai Yang's fr.exe be available on the system in the beginning.

2.1.5 makechm. bat -- use doxygen output to create a CHM File

@ Echo off
Echo converts the encoding of the doxygen output file from UTF-8 to GBK
Set Path = % PATH %; % Cd %
Cd output/html

Echo processes CHM input files
Call utf82gbk. Bat index. HHP
Call utf82gbk. Bat index. HHC
Call utf82gbk. Bat index. HHK
Call html-utf82gbk *. html

Echo generates a CHM File
"C:/program files/HTML Help Workshop/hhc.exe" index. HHP

if exist index.chm copy index.chm ../../refman.chm
del /f /q *.chm
cd ../..


This batch file is assumed that the system has installed "HTML Help Workshop" in the directory "C:/program files/HTML Help Workshop ". Assume that the output directory is the subdirectory output of the doxyfile directory.

2.1.6 rebuild. bat -- regenerate the CHM File

@echo off
call clean.bat
call build.bat
call makechm.bat


Conclusion 2.2

Those who know the doscommand should easily understand the batch processing. After placing these batch files in the working directory (that is, the directory where doxyfile is located), you can re-generate the CHM File every time you type rebuild. If necessary, you can use the clean, build, and makechm commands separately. Utf82gbk and html-utf82gbk commands can also be used separately. You can download these batch files from my homepage www.fmddlmyy.cn.

3. Create a configuration file 3.1. Preparations

"Who raises fish" is a small program I recently wrote. It uses reasoning to solve Einstein's puzzle: "who raises fish ". Readers can download the non-documented program from "poor lifting and reasoning: using the C ++ program to solve" who raises Fish.

Before creating a document, we need to complete the following preparations:

1. Install doxygen, graphviz, and "HTML Help Workshop ". The HTML Help Workshop version I used is 4.74.8702.0 and the English version. The Chinese version is available on the Internet, but an error occurs during running.
2. Put the iconv and FR programs in the directory in the system path, such as C:/Windows/system32.
3. Create an empty directory fish, put the program to be annotated (fish/src), create a working directory for document production (fish/DOC), and put the previously described batch files in the doc directory.

Now you can run doxywizard to create a configuration file.

Click "Save..." to save the configuration in DOC/doxyfile. In this case, the content of doxyfile is the default setting of doxygen. Doxyfile is a common text file, which can be opened and edited directly. However, it is convenient to enter the doxywizard interface. A detailed prompt is displayed for each parameter. We recommend that you use doxywizard to complete the first setting. You can directly edit the doxyfile if you want to adjust some parameters later.

3.2 enter parameters

Click "expert..." to enter the configuration parameters.

:) Does doxygen have many parameters? In fact, most parameters have default values, but not many parameters need to be entered. The following is a page introduction:

3.2.1 project page

Doxyfile_encoding is the text encoding of doxyfile. If the file contains Chinese characters, you can enter GBK.

Enter the project name (project_name), project version (project_number), output directory (output_directory), and output language (output_language ). The output directory can be filled in according to the relative directory of doxyfile. The output language is equivalent to the program resource. Select Chinese.

Doxywizard's Chinese support is incomplete and Chinese characters are garbled. Edit the doxyfile directly and enter:

Project_name = who raised fish

Cancel full_path_names. We modified the following parameters:

Doxyfile_encoding	GBK
Project_name	Who raised fish
Project_number	1.0
Output_directory	Output
Output_language	Chinese
Full_path_names	No

3.2.2 message page

Enter warn_logfile as build. log on the messages page. In this way, doxygen saves the warnings and errors generated during compilation in build. log. We can modify them accordingly.

Warn_logfile

Build. Log

3.2.3 input page

Specify the input source file directory (input) and change the input file encoding (input_encoding) to GBK.

Input	../Src
Input_encoding	GBK

The file_patterns parameter is the file type to be processed by doxygen. The default value includes all file types supported by doxygen. You cannot use doxygen to document any file type. For example, doxygen does not support assembler.

3.2.4 source browser page

Select source_browser to include the source code in the document.

Source_browser

Yes

3.2.5 HTML page

After you select generate_htmlhelp, doxygen prepares the project files, directory files, and index files required by the CHM File. You can customize the page through the html_header and html_footer parameters. The parameter value is the file name that contains the custom content. For example, we can create a file html_foot with the following content:

<P align = "right"> <a href = "http://www.fmddlmyy.cn/text20.html" target = "_ top"> exhaustion and reasoning: use the C ++ program to solve "who raises fish" </a> </P>
</Body>
</Html>

Set the value of html_footer to html_foot.

Generate_htmlhelp	Yes
Html_footer	Html_foot

3.2.6 latex page

Cancel generate_latex without generating latex output.

Generate_latex

No

3.2.7 dot page

On the dot page, you can select uml_look, call_graph, and caller_graph. Call_graph is used by this function to call other functions, for example:

Caller_graph is called by this function, for example:

Uml_look	Yes
Call_graph	Yes
Caller_graph	Yes

3.3 run doxygen

For the "who raises fish" example, the default value can be used for other parameters. After entering the doc directory from the command line (see Appendix 1), run rebuild. BAT to generate refman. CHM. At this time, we have not documented the program, and the output only contains the files generated by doxygen through dot.

We can edit doxyfile, set extract_all to yes, and then rebuild. In this case, doxygen automatically extracts all elements of a program, including files, functions, variables, Type Definitions, enumeration values, and macro definitions.

Anyone who just wants to see the results can download this CHM File. For details about all the parameters in the doxygen configuration file, refer to the "configuration" page in the doxygen manual. The last article ends here. The next section describes how to document programs.

Postscript (2007/7/15)

Many of my friends said they could not produce the expected results according to my instructions. This must be because my article is unclear. Sorry. Recently, I have many things on hand. I am afraid I have no time to write the next article in the past few months. Fortunately, there are still a lot of articles about docization of doxygen on the internet, and I should have nothing to do with this article.

In fact, the purpose of this article is to allow friends who are not familiar with doxygen to quickly understand this tool. If you really want to use doxygen, you should spend more time reading its documentation. I package the working directory of this example on my homepage www.fmddlmyy.cn. You can download it from anyone you need. This is an unfinished version. I removed extract_all and commented out several functions. Because the comments are incomplete, non-empty build. log is generated during compilation (rebuild in the doc directory. Log is a prompt in good faith, which can help us improve the documentation.

Appendix 1 enter the command line and go to the specified directory

If you frequently use the command line, you can create a command prompt hereentry and its sub-item commanders under "hkey_classes_root/folder/shell" in the registry, and set the value of the commandid item to a serial value of cmd.exe ". In this case, you only need to right-click any directory in the resource manager and select "command prompt here" to quickly enter the command line and go to the specified directory.

I saved this registry key as the reg file:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT/Folder/shell/Command Prompt Here]

[HKEY_CLASSES_ROOT/Folder/shell/Command Prompt Here/command]
@="cmd.exe"

You can download the file and double-click it to import the registry.

On Vista, this operation cannot enter the specified directory, nor is it necessary to do so. In Vista: as long as you press the Shift key in the resource manager, and then right-click the folder, the menu item "Open command window here" appears and select. In the left-side directory tree, this operation is invalid.