element14 Community
element14 Community
    Register Log In
  • Site
  • Search
  • Log In Register
  • Community Hub
    Community Hub
    • What's New on element14
    • Feedback and Support
    • Benefits of Membership
    • Personal Blogs
    • Members Area
    • Achievement Levels
  • Learn
    Learn
    • Ask an Expert
    • eBooks
    • element14 presents
    • Learning Center
    • Tech Spotlight
    • STEM Academy
    • Webinars, Training and Events
    • Learning Groups
  • Technologies
    Technologies
    • 3D Printing
    • FPGA
    • Industrial Automation
    • Internet of Things
    • Power & Energy
    • Sensors
    • Technology Groups
  • Challenges & Projects
    Challenges & Projects
    • Design Challenges
    • element14 presents Projects
    • Project14
    • Arduino Projects
    • Raspberry Pi Projects
    • Project Groups
  • Products
    Products
    • Arduino
    • Avnet Boards Community
    • Dev Tools
    • Manufacturers
    • Multicomp Pro
    • Product Groups
    • Raspberry Pi
    • RoadTests & Reviews
  • Store
    Store
    • Visit Your Store
    • Choose another store...
      • Europe
      •  Austria (German)
      •  Belgium (Dutch, French)
      •  Bulgaria (Bulgarian)
      •  Czech Republic (Czech)
      •  Denmark (Danish)
      •  Estonia (Estonian)
      •  Finland (Finnish)
      •  France (French)
      •  Germany (German)
      •  Hungary (Hungarian)
      •  Ireland
      •  Israel
      •  Italy (Italian)
      •  Latvia (Latvian)
      •  
      •  Lithuania (Lithuanian)
      •  Netherlands (Dutch)
      •  Norway (Norwegian)
      •  Poland (Polish)
      •  Portugal (Portuguese)
      •  Romania (Romanian)
      •  Russia (Russian)
      •  Slovakia (Slovak)
      •  Slovenia (Slovenian)
      •  Spain (Spanish)
      •  Sweden (Swedish)
      •  Switzerland(German, French)
      •  Turkey (Turkish)
      •  United Kingdom
      • Asia Pacific
      •  Australia
      •  China
      •  Hong Kong
      •  India
      •  Korea (Korean)
      •  Malaysia
      •  New Zealand
      •  Philippines
      •  Singapore
      •  Taiwan
      •  Thailand (Thai)
      • Americas
      •  Brazil (Portuguese)
      •  Canada
      •  Mexico (Spanish)
      •  United States
      Can't find the country/region you're looking for? Visit our export site or find a local distributor.
  • Translate
  • Profile
  • Settings
Community Hub
Community Hub
Member Blogs Create Firmware Documentation with DoxyGen and Eclipse
  • Blog
  • Forum
  • Documents
  • Quiz
  • Events
  • Leaderboard
  • Polls
  • Files
  • Members
  • Mentions
  • Sub-Groups
  • Tags
  • More
  • Cancel
  • New
Join Community Hub to participate - click to join for free!
  • Share
  • More
  • Cancel
Group Actions
  • Group RSS
  • More
  • Cancel
Engagement
  • Author Author: Jan Cumps
  • Date Created: 30 May 2020 1:07 PM Date Created
  • Views 3795 views
  • Likes 6 likes
  • Comments 5 comments
  • doxygen
  • ccs
  • eclipse
Related
Recommended

Create Firmware Documentation with DoxyGen and Eclipse

Jan Cumps
Jan Cumps
30 May 2020

I'm checking if I can use Doxygen to create documentation for the electronic load firmware.

image

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.

image

This will automatically create a new configuration file for the project.

 

You can then double-click on that file to open the Doxygen editor.

image

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.

image

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.

image

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.

  • Sign in to reply

Top Comments

  • Jan Cumps
    Jan Cumps over 5 years ago +2
    This is how my first attempt looks like:
  • balearicdynamics
    balearicdynamics over 5 years ago in reply to Jan Cumps +2
    Great job, friend. If you want, we can find a couple of hours and I will show you some tricks to make a full site in html, with logo and all the other, as well as an internal search and more. All from…
  • balearicdynamics
    balearicdynamics over 5 years ago +1
    Jan, this is more than a good idea! It is a question of habit. After you take the use to write documentation in the code using the Doxygen syntax, it is automatic to be able to produce software documentation…
  • Jan Cumps
    Jan Cumps over 5 years ago in reply to balearicdynamics +1
    I used javadoc before, so the biggest exercise today was to get doxygen working. Get that first report generated. And to check the doxygen/javadoc syntax differences.
  • DAB
    DAB over 5 years ago +1
    Great post Jan. Documentation is one of the most important aspects of software and firmware development. DAB
  • balearicdynamics
    balearicdynamics over 5 years ago in reply to Jan Cumps

    Great job, friend. If you want, we can find a couple of hours and I will show you some tricks to make a full site in html, with logo and all the other, as well as an internal search and more. All from the source code only. It cost you just a beer (we can meet now, true?)

    • Cancel
    • Vote Up +2 Vote Down
    • Sign in to reply
    • More
    • Cancel
  • DAB
    DAB over 5 years ago

    Great post Jan.

     

    Documentation is one of the most important aspects of software and firmware development.

     

    DAB

    • Cancel
    • Vote Up +1 Vote Down
    • Sign in to reply
    • More
    • Cancel
  • Jan Cumps
    Jan Cumps over 5 years ago

    This is how my first attempt looks like:

    image

    • Cancel
    • Vote Up +2 Vote Down
    • Sign in to reply
    • More
    • Cancel
  • Jan Cumps
    Jan Cumps over 5 years ago in reply to balearicdynamics

    I used javadoc before, so the biggest exercise today was to get doxygen working. Get that first report generated.

    And to check the doxygen/javadoc syntax differences.

    • Cancel
    • Vote Up +1 Vote Down
    • Sign in to reply
    • More
    • Cancel
  • balearicdynamics
    balearicdynamics over 5 years ago

    Jan, this is more than a good idea!

     

    It is a question of habit. After you take the use to write documentation in the code using the Doxygen syntax, it is automatic to be able to produce software documentation on the go. And Doxy support almost all the languages. Also when I have developed pure java (or mostly) like for Android platforms I always preferred doxygen than the inherited javadoc methodology, Doxygen is compatible with, as well as Python and other less used languages.

     

    Enrico

    • Cancel
    • Vote Up +1 Vote Down
    • Sign in to reply
    • More
    • Cancel
element14 Community

element14 is the first online community specifically for engineers. Connect with your peers and get expert answers to your questions.

  • Members
  • Learn
  • Technologies
  • Challenges & Projects
  • Products
  • Store
  • About Us
  • Feedback & Support
  • FAQs
  • Terms of Use
  • Privacy Policy
  • Legal and Copyright Notices
  • Sitemap
  • Cookies

An Avnet Company © 2025 Premier Farnell Limited. All Rights Reserved.

Premier Farnell Ltd, registered in England and Wales (no 00876412), registered office: Farnell House, Forge Lane, Leeds LS12 2NE.

ICP 备案号 10220084.

Follow element14

  • X
  • Facebook
  • linkedin
  • YouTube