Integrating Doxygen with Eclipse - theolind/mahm3lib GitHub Wiki

Introduction

In this tutorial we will be integrating the Doxygen code documentation generator into Eclipse, for fast, easy doc-generation across multiple developers. This is done using the Eclox-plugin which bridges the gap between Doxygen and Eclipse.

Requirements

  • Windows, Mac or Linux operating system
  • Eclipse
  • Java Runtime Environment 1.4.2 and above

Preparing the Doxygen Software for Eclipse integration

There are three subsections in this section. Each explains the necessary steps for integrating Doxygen into Eclipse on a specific operating system. There is one for Mac OS, one for Windows os and one for Linux OS.

Using Mac OS

  1. Download the Mac-version of Doxygen. It is a .dmg file and its download links are located under "A binary distribution for Mac OS X 10.5 and later": http://www.stack.nl/~dimitri/doxygen/download.html Note: As of writing this wiki - the latest available version is 1.8.8. This version should be used by all developers throughout the development to minimize bugs caused by software version differentials.

  2. Open "Doxygen-1.8.8.dmg". In the new window that has opened you should see "Doxygen.app". Move the Doxygen.app to /Applications.

  3. The Doxygen software for Mac is now ready for Eclipse integration!

Using Windows OS

  1. Download the Windows-version of Doxygen. It is an .exe file and its download links are located under "A binary distribution for Windows. All versions of Windows since XP are supported.": http://www.stack.nl/~dimitri/doxygen/download.html Note: As of writing this wiki - the latest available version is 1.8.8. This version should be used by all developers throughout the development to minimize bugs caused by software version differentials.

  2. Double-click the downloaded .exe file and follow the installation wizard.

  3. Done! Now Doxygen is ready to be integrated into Eclipse!

Using Linux OS

  1. Download the Linux-version of Doxygen. It is an .tar.gz file and its download links are located under "A binary distribution for Linux x86-64": http://www.stack.nl/~dimitri/doxygen/download.html Note: As of writing this wiki - the latest available version is 1.8.8. This version should be used by all developers throughout the development to minimize bugs caused by software version differentials.

  2. Open up a shell and run these: tar -xzvf doxygen-1.8.8.linux.bin.tar.gz cd doxygen-version ./configure make install You might see an error message when executing that last command: /usr/bin/install: cannot stat ‘bin/doxytag’: No such file or directory It's nothing to worry about, read about it here: http://stackoverflow.com/questions/15020691/installation-of-doxygen-and-error-in-make-command

  3. Now Doxygen is ready for Eclipse integration!

Integrating Doxygen with Eclipse

  1. Open up Eclipse and navigate to Help --> Install New Software

  2. In the new window that has appeared, copy paste this link to the textfield next to "Work with:": http://download.gna.org/eclox/update Also Check the box next to "eclox" in the list and then press "Next".

  3. Press "Next" again then "Finish"

  4. A frame like this can appear, just press "OK"

  5. A frame will ask you to restart Eclipse, just press "Yes"

  6. If you're on Windows, go to "Window --> Preferences --> Doxygen", if you're on Mac, go to "Eclipse --> Preferences --> Doxygen".

  7. Now you need to add the Doxygen files. The location you should add differs from the operating systems. -Mac OS: Press Shift+CMD+G then Add: "/Applications/Doxygen.app/Contents/Resources/doxygen" -Windows OS: Add "C:\Program Files\doxygen\bin" -Linux OS: Add "/usr/local/bin" (The image below demonstrates the procedure in Mac OS)

  8. Check the box next to your added directry, then press "Apply", then "OK"

  9. Doxygen is now integrated into Eclipse!

Source: http://www.mantidproject.org/Eclipse_Doxygen_Setup

Setting up the initial Doxygen config for project

This procedure should be the same in Linux, Windows and Mac OS.

  1. First the Doxygen configuration file needs to be created. This config is generated once for every Eclipse workspace. Open up Eclipse and the workspace containing the projects you want to document.(If you don't have an example code to try it on yet, you can open up an example Hello-world C-project for this demonstration)

  2. You should notice a new small -button next to the "Debug"- and "Run" buttons. Press that button. In the new frame that appeared, just press "Yes".

  3. Now you need to choose the location to store the Doxygen configuration file. Best practise is storing the file in the root of your main project. Meaning it should be in the same folder as "Debug" and "src". This will allow version control software like GitHub to backup the Doxygen configuration file and allow multiple developers the ability to generate documentation.

  4. Now double-click the new .doxyfile created in the root of your main project. This will open up a new window in Eclipse, where you can customize the Doxygen configuration

  5. Enter a name and version for your project

  6. Choose the "Input Directory". This is where you choose the directory of the project you want to document. If you created the .doxyfile in the root of the main project, then you should see "src" in the list after you added the "src"-folder of your project. Now choose the "Output Directory". This directory is where your generated documentation should be stored. This should just contain a "." after choosing your project.

  7. Some more options can be customized, choosing "all entities" under "Select the desired extraction mode:" will generate documentation for all source code files, even if they do not contain any documentation.

  8. Last configuration-step needed is choosing the "Output Formats". Usually generated HTML-docs should be enough but other opportunities like documentation in Latex and XML exists.

  9. Save the configuration file, then press the -button! Choose your .doxyfile in the new frame then press "OK". Now you should have successfully generated documentation using Doxygen!

  10. A new folder called "html" should be created in the project root folder. In that folder double-click "index.html". This should open up the generated documentation.

  11. Press the -button each time you want to generate/update the docs for your project.

Usage

How to properly comment the source code for Doxygen compatibility can be read in the Coding Convention wiki

Sources

Read more from the Doxygen manual: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

Read more from the Doxygen special command manual: http://www.stack.nl/~dimitri/doxygen/manual/commands.html

Example website showing more Doxygen possibilities: http://www.stack.nl/%7Edimitri/doxygen/manual/examples/author/html/index.html