I'm checking if I can use Doxygen to create documentation for the electronic load firmware.
Doxygen is an application that can generate documentation based on declarations and comments in the source code. The eLoad firmware uses an API style that should easily adapt to Doxygen's way of working. The goal of this post is to get Doxygen utilities set up in Eclipse, document a first function and generate HTM documentation. |
I used this document to set up Doxygen and integrate it in Eclipse. This was a simple process.
When complete, you get additional functionality, buttons and an editor to start working.
Add Doxygen to your Project
The first step is to add the Doxygen configuration. Select your project in the Eclipse Explorer.
Then click the small arrow next to the brand new Doxygen button and select Build Doxyfile.
This will automatically create a new configuration file for the project.
You can then double-click on that file to open the Doxygen editor.
I've used these settings to allow a slow and soft start, only documenting the project's main API..
Another option would be to generate maximum output by just checking Scan recursively and the All Entries mode.
Annotating the API functions
You build the documentation by annotating the elements in the project.
Here's an example:
/** * This function expects the resistance of the NTC thermistor at the point where the electronic load is overheated. * It then calculates, based on the fact that the voltage is 5V and that the NTC is the lower part of a voltage divider * where the other resistor is 10K, the voltage that appears on ADC 3 if the maximum temperature is reached * @param value the NTC cutoff resistance * @return true if in calibration mode. false if executed while the instrument was not in calibration mode. */ bool eloadCalibrateSetTemperatureMaxResistance(uint32_t value);
You can write the documentation in header or source file. I've chosen the header because I'm documenting the public API functions.
There's discussion on this here and here. I may change my mind if putting it in the source files works easier for me.
Generate the Report
When you press the @ button in Eclipse, the documentation is regenerated. You can then view the results in a browser.
This works fairly straightforward. And fulfills what I tried to achieve here.
Version Control notes
I usually don't add generated files to version control. In this case the HTML docs and (if selected) Latex files.
To avoid that a next commit will add these files, use your version control's ignore options to exclude the html and latex subdir of your Eclipse project.
If you use Git, the easiest way to do this is to run the Doxygen generator once, then right-click on these newly generated folders, then select Team -> Ignore.
I have added the Doxygen configuration file to version control because I want this to become a part of the core. Like the make file.
Top Comments