How to install and use doxygen

How to install and use doxygen

[Precodition]

OS         : Redhat Fedora 2

Doxygen    : 1.3.6

 

Doxygen is a very famous tool to generate automatically detailed documentation in the light of commentary of source codes. It supports C++, C, Java, IDL(Corba, Microsoft, and KDE-DECOP flavors) and to some extent PHP and C#. If you are familiar with Java, it is equivalent to javadoc tool which is a documentation system for java. It can help you in three ways:

1. It can generate an on-line documentation browser(in HTML) and/or an off-line reference manual(in LATEX) from a set of documented source files. There is also support for generating output in RTF(MS word), Postscript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

2. You can configure doxygen to extract the code structure from undocumented source files. The is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams and collaboration diagrams, which are all generated automatically.

3.    You can even ‘abuse’ doxygen to create normal documentation.

 

[Essential tools]

☆ flex        : GNU fast lexical analyzer generator

☆ bison       : GNU project parser generator(yacc replacement)

☆ make

☆ perl

☆ Qt           : GUI toolkit, please visit relative contents in my blog website.

☆ latex        : An famous MACRO package tool

☆ graphviz

☆ ghostscript  : PDF language interpreter and previewer

 

[How to install]

There are two ways to install doxygen. First one makes full use of binary file of doxygen. Compared with the second, it is easier. So the following contents focus on how to install doxygen by source codes.

To be supposed that you have obtained source codes of doxygen. If readers don’t know where to download them, please visit www.doxygen.org.

1. Copy file into proper directory and unpack the archive

#tar xvzf ./doxygen-$VERSION.src.tar.gz

2. Run configure script

#cd doxygen-$VERSION

#./configure

Script will automatically search relative platform and tools. If essential tools have not been found, error information will be shown and you must install them before installing doxygen. Of course, users can customize how to configure it. For example, ‘—platform’ (#./configure  --platform platform-type) can been utilized when users want to change platform. If Qt tool has existed, ‘--with-doxywizard’(#./configure --with-doxywizard) may be deployed to build GUI-front end. For an overview of other configuration options, please use ‘#./configure --help‘ to get it.

3. Compile doxygen. After finished compiling, doxygen, doxytag and doxysearch will be produced

#make

4. Generate user manual

#make docs

#make pdf

‘make docs’ generates HTML format’s user manual, and pdf format’s user manual is created by the ‘make pdf’ commandJ.

5. Install doxygen

#make install

Binaries will be installed into <prefix>/bin directory, and <docdir>/doxygen directory stores documentations and examples. Users can use ‘./configure –prefix or --docdir’ to change locations, and the default <dordir> directory is <prefix>/share/doc/packages.

 

[Doxygen information flow]

Doxygen is a key tache that connects with doxytag and doxysearch. It will parse source codes and read external doxygen documentations to generate or update doxygen documentations in the light of customized format. It can be concluded from figure 1 that doxygen is main program and doxytag is only needed if users want to generate to external documentations (i.e. documentation that was generated by doxygen) for which users do not have the sources or to create a search index for the search engine. Moreover, doxysearch will take an important role in the search engine. From the figure 1, users can easily find that doxywizard provides GUI to edit configuration file of doxygen, and it is a friend tool to manage doxygen later.

Figure 1 Doxygen Information Flow

 

[Doxygen description style]

Doxygen has two kinds of description style, which combine with a documentation: a brief description and detailed description. However, they are optional. The following contents will focus on these two types of description.

 

Detailed description

 

1. If readers are familiar with Java, this style is coherent with javadoc.

/**

 * detailed description

 */

2. The style of Qt has been adopted in doxygen.

/*!

 * detailed description

 */

3. The above intermediate stars are optional, so you can do like this:

/**                                  /*!

  Detailed description     or      detailed description

*/                                   */

4. Use commentary of C++’s style besides an additional slash or exclamation will be followed.

///                                      //!

/// detailed description     or     //! Detailed description

///                                      //!

   Or

/

/// detailed description

 

Brief description

 

1. Use/brief command and detailed description will be followed after an empty line.

/*! /brief Brief description

 *           continuing brief description

 *

 * detailed description

 */

2. JAVADOC_AUTOBRIEF is set to YES in the configuration file, using JavaDoc style comment blocks will automatically start a brief description which wends at the first dot followed by a space or new line.

For C or C++

/** Brief description.             /** Brief description. Detailed

 * detailed description      or     *  description

 */                                     */

For C++

/// Brief description.               /// Brief description. Detailed

/// detailed description      or   /// description

///                                     ///

3. Otherwise, JAVADOC_AUTOBRIEF is set to NO and use C++ style

/// Brief description

/** detailed description */

 

Or

//! Brief description

 

//! Detailed description

Furthermore, if there is one brief description before a declaration and one before a definition of a code item, only the one before the declaration will be used. If the same situation occurs for a detailed description, the one before the definition is preferred and the one before the declaration will be ignored.

 

[Doxygen commands]

Sometimes programmers want to place commentary before namespace, class, function, variables, etc. Doxygen supports these operations. However, the payment is that programmers must use structural command started with a backslash (/) or an at-sign (@) which is followed by doxygen command and one or more parameters.

 

Doxygen commands

☆ /struct to document a C-struct.

☆ /union to document a union.

☆ /enum to document an enumeration type.

☆ /fn to document a function.

☆ /var to document a variable or typedef or enum value.

☆ /def to document a #define.

☆ /file to document a file.

☆ /namespace to document a namespace.

☆ /package to document a Java package.

☆ /interface to document an IDL interface.

 

Sample structcmd.h

/*! /file structcmd.h

/brief A Documented file.

Details.

*/

 

/*! /def MAX(a,b)

/brief A macro that returns the maximum of /a a and /a b.

Details.

*/

 

/*! /var typedef unsigned int UINT32

/brief A type definition for a .

Details.

*/

 

/*! /var int errno

/brief Contains the last error code.

/warning Not thread safe!

*/

 

/*! /fn int open(const char *pathname,int flags)

/brief Opens a file descriptor.

/param pathname The name of the descriptor.

/param flags Opening flags.

*/

 

/*! /fn int close(int fd)

/brief Closes the file descriptor /a fd.

/param fd The descriptor to close.

*/

 

/*! /fn size_t write(int fd,const char *buf, size_t count)

/brief Writes /a count bytes from /a buf to the filedescriptor /a fd.

/param fd The descriptor to write to.

/param buf The data buffer to write.

/param count The number of bytes to write.

*/

 

/*! /fn int read(int fd,char *buf,size_t count)

/brief Read bytes from a file descriptor.

/param fd The descriptor to read from.

/param buf The buffer to read into.

/param count The number of bytes to read.

*/

 

#define MAX(a,b) (((a)>(b))?(a):(b))

typedef unsigned int UINT32;

int errno;

int open(const char *,int);

int close(int);

size_t write(int,const char *, size_t);

int read(int,char *,size_t);

 

[Tips]

How to create template of configuration file?

Use syntax: doxygen –g <config-file > to create template. If <config-file> has been omitted, ‘Doxyfile’ will be produced. If ‘Doxyfile’ has existed, original file will be renamed as ‘Doxyfile.bak’.  For example:

#doxygen –g dragoon-doxy

Dragoon project’s configuration file will be generated in the current directory. If qt is available in users’ system, doxywizard can be used for GUI.

 

[How to generate list]

Doxygen has a number of ways to create lists of items.

1. Using dashes

By putting a number of column-aligned minus signs at the start of a line, a bullet list will automatically be generated. Numbered lists can also be generated by using a minus followed by a hash.

/*!

* A list of events:

* - mouse events

*    -# mouse move event

*    -# mouse click event/n

*        More info about the click event.

*    -# mouse double click event

* - keyboard events

*    -# key down event

*    -# key up event

*

* More text here.

*/

 

Result:

A list of events:

·mouse events

1. mouse move event

2. mouse click event

More info about the click event.

3. mouse double click event

·keyboard events

1. key down event

2. key up event

You can end a list by starting a new paragraph or by putting a dot (.) on an empty line at the same indent level as the list you would like to end.

For example:

/**

* Text before the list

* - list item 1

*   - sub item 1

*      - sub sub item 1

*      - sub sub item 2

*      .

*      The dot above ends the sub sub item list.

*      More text for the first sub item

*   .

*   The dot above ends the first sub item.

*   More text for the first list item

*   - sub item 2

*   - sub item 3

* - list item 2

* .

* More text in the same paragraph.

*/

 

2. Using HTML commands

/*!

* A list of events:

* <ul>

*    <li> mouse events

*        <ol>

*            <li>mouse move event

*            <li>mouse click event/n

*                 More info about the click event.

*            <li> mouse double click event

*        </ol>

*    <li> keyboard events

*        <ol>

*             <li>key down event

*             <li>key up event

*        </ol>

* </ul>

* More text here.

*/

 

3. Using /arg or /li

/arg /c AlignLeft left alignment.

/arg /c AlignCenter center alignment.

/arg /c AlignRight right alignment

/c <word> displays word using typewriter font.

/b <word> displays word using bold font.

Result:

·AlignLeft left alignment.

·AlignCenter center alignment.

·AlignRight right alignment