GRAB common libraries and utilities, project independent.
This repository contains common utilities for different projects developed at GRAB lab. They are organized in library form, divided by topic:
To auto-generate an user-friendly documentation straight out of the source code, we make use of well-known software tool Doxygen. On the official website you can find all the details about how to use it, install it and build it. While we provide here a short tutorial on how to integrate it in our Qt-based framework, we leave to the user the task of reading the manual on the format to be employed when writing documentation within the code. Bear in mind that in this project we opted for JavaDoc style, so please comply with it.
First of all, you need to download the tool itself (you can skip this step if it is already installed in your machine).
To do so, open a terminal and type the following command:
sudo apt-get install doxygen doxygen-gui
That’s it. Now Doxygen is installed and ready to be used.
Next, you need to setup a Doxyfile, which yields all the instructions to generate the documentation out of your code. Instead of compiling this file yourself, Doxygen provides a nice wizard to walk you throug all the necessary step: doxywizard.
To start it, just type doxywizard
in a terminal and a small GUI will appear.
Feel free to adapt the settings to your specific need, but the minimal setup for this library should include the following:
Step 1
, select $MYPROJECTPATH, where $MYPROJECTPATH is the absolute path to your project root directory.Step 2
, in the tab Wizard
, select Project
under Topics
and do the following:Project name
, as desiredSource code directory
and tick Scan recursively
option belowDestination directory
(make directory if it does not exist yet)Step 2
, in the tab Wizard
, select Output
under Topics
and untick LaTeX option unless desired.Step 2
, in the tab Expert
, select HTML
under Topics
and tickUSE_MATHJAX
option to display mathematical formulas.Step 2
, in the tab Expert
, select Input
under Topics
, go to FILE_PATTERNS
and remove all extensions except *.c, *.cc, *.cpp, *.c++, *.h, *.hh, *.hpp, *.h++ by selecting them and clicking the minus button. Look below for EXCLUDE_PATTERNS
and add tests and doc by clicking the plus button. In the EXCLUDE
list right above you should also add any build folder which is inside the source code directory. Finally add the following words to the EXCLUDE_SYMBOLS
list:Step 2
, go to tab Run
and click Run doxygen
button. In the integrated console you will see your documentation building up. When it is done, click on Show HTML output
and you will be prompted to a web page on your favourite browser, which you can navigate on.Assuming the code you want to document already belongs to a Qt project, open it with QtCreator and go to Projects tab. In the Build Settings, under the Build Steps section, click on Add Build Step
button and select Custom Process Step
.
In the Command
field type doxygen
, while in the Arguments
field you need to write the absolute path to the Doxyfile we just created, i.e. $MYPROJECTPATH/Doxyfile.
That’s it! On your next build, Doxygen will parse all the files present in the project, look for documented lines within the code and generate an html
file with all the information found nicely arranged.
The main file you want to open is index.html
, which you will find in the specified doc folder.
Note that Doxygen may generates a lots of warning, especially the first times you use it, because your code is probably not yet compliant with all the formatting rules. These warnings do not affect the performance or outcome of your application, but can hide serious ones generated because of specific user-specific errors, unrelated to documentation. Our suggestion is to lose some time at the beginning to solve them one-by-one, and add compliant comments while developing new code right away as you move forward. It is a good practise which makes life easier for you and especially for your future and present colleagues! :)