Creating documentation is an important and often neglected aspect of software engineering. One part of documentation is putting comments in the code source files themselves, explaining what the code is doing and how it is doing it. This is important so others looking at your code can better understand what it does and how it does it. Another aspect of documentation is the creation of separate reports. These reports often contain the API or Application Programming Interface of the code they document.
Doxygen is a tool that can simplify the creation of software reports. It does this by using special C++ comments that are added directly in the source code. The source code is run through the Doxygen tool and it can automatically create documentation in HTML and Rich-text format (Word) amongst others.
Doxygen can be downloaded from here. It is available for Windows, macOS and Linux. A standalone version for Windows (that does not need administrator privileges to install and so is useful for using in the lab) is available and included in the required file for this lab.
Doxygen must be configured before it can be used. It is done so through configuration files. We can generate a template config file by running the following code inside the project directory
eencae@EENTPC115 /m/home/109/Circle $ ../Doxygen/doxygen.exe -g
Note here the path to the standalone Doxygen executable i.e. we have to go up one level, then down in to the Doxygen directory. You may not have to do this if you install Doxygen on your own machine.
This step creates a configuration file named Doxyfile that can be edited in a text editor (e.g.
Visual Studio Code). There are lots of options that must be searched through (using the find option of your
editor). Below is a summary of the changes that need to be made.
PROJECT_NAME = Circle PROJECT_NUMBER = 1.0 PROJECT_BRIEF = C++ class for calculating the area of a circle OPTIMIZE_OUTPUT_FOR_C = YES GENERATE_HTML = NO GENERATE_LATEX = NO GENERATE_RTF = YES RTF_EXTENSIONS_FILE = extensionsFile
Here we give a name and version number along with a brief description. We then tell it to optimise for C since we are using it for this language. We do not want to generate HTML (although this is useful for Internet-based documentation) or LaTeX documentation. We do however want to generate RTF format so we can open it in Microsoft Word. We also tell it the name of a configuration file for RTF output.
We can create a template to modify by running the following command.
eencae@EENTPC115 /m/home/109/Circle $ ../Doxygen/doxygen.exe -e rtf extensionsFile
We can then edit extensionsFile in a text editor and make the following changes by uncommenting
the relevant lines (remove the #) and adding the details.
Company = University of Leeds Author = Dr Craig A. Evans DocumentType = Application Programming Interface
It is now a simple case of running Doxygen using our Doxyfile.
eencae@EENTPC115 /m/home/109/Circle $ ../Doxygen/doxygen.exe Doxyfile
This will print some output to the command line and creat a directory containing our report.
Searching for include files... Searching for example files... Searching for images... Searching for dot files... Searching for msc files... Searching for dia files... Searching for files to exclude Searching INPUT for files to process... Searching for files in directory M:/home/109a/Circle Reading and parsing tag files Parsing files Preprocessing M:/home/109a/Circle/Circle.cpp... Parsing file M:/home/109a/Circle/Circle.cpp... Preprocessing M:/home/109a/Circle/Circle.h... Parsing file M:/home/109a/Circle/Circle.h... Preprocessing M:/home/109a/Circle/main.cpp... Parsing file M:/home/109a/Circle/main.cpp... Building group list... Building directory list... Building namespace list... Building file list... Building class list... Associating documentation with classes... Computing nesting relations for classes... Building example list... Searching for enumerations... Searching for documented typedefs... Searching for members imported via using declarations... Searching for included using directives... Searching for documented variables... Building interface member list... Building member list... Searching for friends... Searching for documented defines... Computing class inheritance relations... Computing class usage relations... Flushing cached template relations that have become invalid... Computing class relations... Add enum values to enums... Searching for member function documentation... Creating members for template instances... Building page list... Search for main page... Computing page relations... Determining the scope of groups... Sorting lists... Freeing entry tree Determining which enums are documented Computing member relations... Building full member lists recursively... Adding members to member groups. Computing member references... Inheriting documentation... Generating disk names... Adding source references... Adding xrefitems... Sorting member lists... Computing dependencies between directories... Generating citations page... Counting data structures... Resolving user defined references... Finding anchors and sections in the documentation... Transferring function references... Combining using relations... Adding members to index pages... Loading RTF extensions extensionsFile... Generating style sheet... Generating search indices... Generating example documentation... Generating file sources... Generating code for file Circle.h... Generating file documentation... Generating page documentation... Generating group documentation... Generating class documentation... Generating docs for compound Circle... Generating namespace index... Generating graph info page... Generating directory documentation... Generating index page... Generating page index... Generating module index... Generating namespace index... Generating namespace member index... Generating annotated compound index... Generating alphabetical compound index... Generating hierarchical class index... Generating member index... Generating file index... Generating file member index... Generating example index... finalizing index lists... writing tag file... Combining RTF output... lookup cache used 7/65536 hits=19 misses=7 finished...
Assuming all runs as expected, the report will be generated. When it is opened in Microsoft Word, the fields must be updated for the table of contents, page numbers and index to be populated. This is done by selecting all the text, right-clicking and updating the fields.