Updated April 7, 2023
Introduction to Doxygen
Doxygen is a tool or command line-based documentation generator that helps in writing reference documentation for software. As it is written within the code, it is very easy to keep on updating. Moreover, it can cross-reference the code and documentation, which helps in referring to the actual code. Due to these advantages, developers are now using Doxygen for their documentation. In addition to that, it supports different programming languages. In this article, we will see more details on Doxygen.
Why do we need Doxygen?
As already explained, Doxygen is a tool that helps in writing reference documentation for different programming language such as Java, C, C++, C#, IDL, D etc.
In addition to that, Doxygen can be used for the
- creation of template configuration file,
- generation of documentation using a conf file which is already available
- updating of the old configuration file, etc.
More details on these will be explained under the heading Uses of Doxygen.
How Doxygen works?
Now, we are going to look at the working below:
1. Select the programming language
For working in Doxygen, first, there should be an assurance that the programming language you are about to choose is recognized by this tool. If not, then choose another method. Normally, Doxygen supports different programming languages such as C, C++, IDL, C#, Java, Objective C, VHDL, Python, D, PHP and Fortran.
Once you select your programming language to be used in Doxygen, create a conf file. That is configuration file. This file decides all the settings, and each of the project in Doxygen will have its own configuration file. As we all know, a project contains either a single source file or a whole source tree which has to be recursively scanned. For 1making conf file in an easy way, a template can be created by Doxygen using the command doxygen -g <conf-file>. Here, the <conf-file> is the configuration file’s name. Suppose you are not using the name of the file; in that case, a file will be created with the name as Doxyfile. In the case where there is already a file with this name, doxygen renames the same to <conf-file>.bak prior to the creation of the configuration template. If the minus sign is used in the created file name, it will be able to read from standard input (stdin), which helps in scripting.
2. Run Doxygen
In order to make the documentation, run the command doxygen <conf-file>.
Once this command is executed, an html, latex, rtf, xml, docbook or man directories will be created within the output directory. The type of document depends on the settings you have provided in the doxygen. From the type of files themselves, we can understand that these directories consist of the documentation in RTF, HTML, Unix-Man page, LATEX, DocBook and XML format.
In this, the default output directory is the one in which it starts. Moreover, the root directory where the output will be written to can be changed with the help of OUTPUT_DIRECTORY. Inside this OUTPUT_DIRECTORY, the directory which is format-specific can be chosen using DOCBOOK_OUTPUT, HTML_OUTPUT, MAN_OUTPUT, RTF_OUTPUT, XML_OUTPUT, and LATEX_OUTPUT.tags of the conf file. Similar to the creation of the conf file, if the output directory also does not exist, the doxygen will be creating one.
3. Documentation of the sources
Even though the source documentation is explained as the third step, it should be explained as the first step in the case of a new project. Suppose the option EXTRACT_ALL is marked as No in the conf file; documentation will be generated by doxygen only for the documented entities. In order to document these, there are two methods, especially for classes, members and namespaces. The first one is to set a specific documentation block prior to the member/class/name space declaration or definition for file, class and namespace members; it is also allowed to place the documentation directly after the member.
The second way is to place the specific documentation block anywhere else. That is another location or file. Once it is placed, place a structural command within the block. The task of structural command is to connect the documentation block to a specific entity like member, namespace, class or file, which is possible to be documented. The main advantage of the first method is that the entity name need not be repeated.
Advantages and disadvantages
Advantages are:
- Only less overhead is required from the one who writes the documentation.
- Documentation of unions, files, templates, namespaces, enums, classes, functions, structs, typedefs, variables, and defines is supported.
- Compatible with JavaDoc (1.1), KDOC and Qt-Doc
- Class diagrams are generated automatically in HTML
- Dependency graphs, graphical class hierarchy graphical graphs etc., can be created using the tool known as a dot which is available in the tool kit known as Graphviz.
- Documentation can be kept within the header file, source file or in another file.
- A list of class members can be generated with their protection level.
- All the sections which are public, private as well as protected can be automatically detected.
- Transferring to other machine or location is possible for the documentation as well as a search engine.
- Easy to work even in large projects.
Even though it has several ways to include searching for the HTML output, it has certain disadvantages.
- Client side searching is limited to symbols only rather than ful text searching.
- Server side searching does not behave properly while working locally.
- Compilation of the CHM file works on only Windows
- Mac OSX and Xcode works only in combination.
Usage of Doxygen
As already explained. It can be used to create template configuration files, generate documentation using a conf file, etc. Now, we will see how.
- Generation of template conf file: doxygen [-s] -g [confName]
- Updation of an old conf file: doxygen [-s] -u [confName]
- Generation of documentation using an already available configuration file: doxygen [confName]
- Generation of a RTF/HTML/Latex template stylesheet file : doxygen -w rtf styleSheetFile
- Generation of extension file of RTF : doxygen -e rtf extensionsFile
Conclusion
It is a tool that helps in writing reference documentation for different programming languages. In this article, different aspects such as usage, working, pros, and cons are explained in detail.
Recommended Articles
This is a guide to Doxygen. Here we discuss Why do we need Doxygen and How it works with usage, Advantages and disadvantages. You may also have a look at the following articles to learn more –
