Use Doxygen
Written / k. Young translation / Marvida
(Published in "programmer" 2002 No. 3)
First, introduction
The Glast software has used Doxygen (GNU GPL software) as a document tool, which will provide a brief introduction. To learn more detailed information and download the Doxygen program, please visit http://www.stack.nl/~dimitri/doxygen/.
What is doxygen? The following introduction is recorded from the Doxygen's page:
"Doxygen is a document system for C , IDL (Corba, Microsoft and KDE-2 DCOP style) and C. It can help you in three ways:
1. It can generate an online document browser (HTML format) from a set of documents, and / or offline reference manuals (Latex format). It also supports the generation of RTF (MS-Word), PostScript, hyperlink PDF, compressed HTML, and UNIX MAN page formats. The document is directly extracted from the source file, so it is very easy to keep the document and the source code.
2. You can configure the DOXYGEN to extract the code structure from the source file that is not labeled. This is very useful for the things you want to quickly find what you need in a large source file. The relationship between different ingredients can be visually visually via the incrude dependent diagram, inheritance map, and collaboration maps (they are automatically generated).
3. You can even "abuse" Doxygen, create a normal document. "
Second, DOXYGEN comment style
The first step in using Doxygen is to insert a Doxygen style comment in your code. You can use two different styles of Doxygen notes:
Qt style, dedicated document block looks like this: / *! ... text ... * / also has a single line version: file: //! ... one line of text ... javadoc style, dedicated document block It looks like this: / ** * ... text ... * / There is a single line version: /// ... One line of text ...
From now on, I will use Qt style in the example, but you can use any one in your code.
You can use Doxygen annotations in many ways to write documents for your code. But one of the following, we feel satisfactorily. Note The following annotations are only explained using the Doxygen annotation; you should include the information in the comment is another thing, not here to discuss.
Our basic idea is to increase short note and long comments for each class, and important member functions of such classes. Short Narve Releases should give a brief description of basic information from class or functions. For longer annotations, it is not surprising that longer and more complete descriptions should be given. The short description of the class and long comments, and the short description of the member function will be placed in the header file. The long press release of the member function will appear in the event of the implementation of the member function.
The following example demonstrates this annotation system (apologize to Alexandre, Regis, and Jose, I "black" in this process). Assuming that we are working for a CMT package called Calpack, it has a separate class csicluster, the header file is called csicluster.h, in the Calpack / directory; the implementation file is called csicluster.cpp, in the src / directory . Document Calpack / CSICLUSTER.H is this:
And the file src / csicluster.cpp is like this:
Note that you might choose to omit the longer annotations of those who have clear member functions, which will not cause any problems. Visit http://www.slac.stanford.edu/exp/glast/round/software/doxygen_examples/v1/class_csicluster.html You can see the HTML document generated by the commented code. Third, use the mainpage.h file
Browse the document in the link above, you may notice the link called "main page" (it pointing index.html) is not very interesting. This is a special page where you can add documents related to all classes described with your Doxygen page. There is only one separate class in our example, but you can use Doxygen to handle so many classes you choose. A natural division is to create a Doxygen page for each Glast CMT package. So imagined, we want this home page to become a description of the package being discussed; in our case is the Calpack package.
So how do we add content to this main page? You need to use Doxygen's special command / mainpage. There are some special commands in Doxygen, they are placed in the Doxygen Comment to enhance the document you generated. For example, in the class description, we have used Doxygen Special Command / Author.
Command / MainPage Specifies the contents of the annotations used to populate the master page. Doxygen allows you to put this command in any comment. However, Glast's convention is to place the command in file mainpage.h. This mainpage.h file should only contain a comment using the / mainpage command. And this file should be placed in the header file directory, that is, the same directory as the package yourself.
So we create a CalPack / MainPage.h file for the CalPack package:
Note that the words behind the / mainpage command are the title of the main page. We also introduce / section commands, which you should be able to derive it. The HTML output generated above is http://www.slac.stanford.edu/exp/glast/round/software/doxygen_examples/v2/. You can also access the CSICLUSTER class's documentation here.
Fourth, including images
Another interesting command (for this we want to implement some standard) is / image command. This command is used to insert an image in your document. The / image command can be used in any comment. The syntax of this command is as follows:
/ image html mypicture.gif
Although we only show HTML output, Doxygen can also be used to create a LaTex, Man or RTF document. However, not all formats support all image types. Thus, it is necessary to specify the output format of the image you want to contain. Doxygen will find image files in the directory you specified by variables called Image_Path. The settings for this variable and other Doxygen default values will be explained in "Run Doxygen" below. Currently, just pay attention to GLAST's practice is a directory called a doc / images / directory for all image files used for the given package in your document.
So it is assumed that an image file called FigureSim2.gif is in directory DOC / IMAGES /, we want to insert it into our homepage, we can complete with simple changes:
The generated HTML output is shown at http://www.slaac.stanford.edu/exp/glast/round/software/doxygen_examples/v3/.
V. Run Doxygen
You can run Doxygen in two ways. Note that both methods require you to install Doxygen on your access path. Visit the Doxygen's homepage to get information about downloading and setting up the executable.
1) For VCMT users, you can simply click on the "CREATE" button in the Doxygen area to create an HTML document for all packets you selected. Then click "EXAMINE" to view the page. 2) For non-VCMT users, you first need to create a DoxyFile. DoxyFile allows you to set all the settings and paths required to run Doxygen. To create a DoxyFile, do doxygen -g
Once you set these parameters and any other parameters you want to change, you can run Doxygen. Suppose your doxyfile is called "doxyfile", execute
Doxygen DoxyFile
It will parse all the files you specify. By default, the HTML output will be placed in a directory called an HTML / (this can also be changed in DoxyFile).
Translator Note:
1. Doxygen has built-in multilingual support, currently supporting 24 languages, including Chinese. Please refer to Doxygen's reference manual for specific usage.
2. Glast is an abbreviation of the Gamma Ray Large Area Space Telescope. Homepage At http://www-glast.stanford.edu, its source code can be accessed via CVS.
