Doxygen

Doxygen is a program/system for extracting comments from code sources files and auto-magically turning those nicely written comments into nicely presented technical documentation for your application (see example).  Ok, I know I am banging on and on about this but there are so many reasons this is a good thing for you to do:

1. Commenting your code is a very good thing to do:
   • it can help to think in plain english before writing in code;
   •  it serves to remind you of what you were thinking about long after you have forgotten what it was you did – which trust me will happen more and more as your programs grow in complexity and length.
2. The tendency to copy code from the web without any understanding for what it does is high – adding your own comments forces you to step through that code gaining an understanding.
3. Eventually others(teachers/fellow coders) will refuse to bug fix your code without comments to help them see what you were thinking/trying to do.

The more complex your applications become the more important commenting is.  If you are completing coursework for school you can often gain value added by using a documenting system like Doxygen because the time consuming process of generating evidence, screenshots and documentation is done for you.

OK , OK, I’M CONVINCED – HOW DO I GO ABOUT DOING THIS?

Download and install Doxygen from their homepage.  This is my config file or alternate here which you should be able to use as a starting point – remove the .txt file extension. So starting from the very top of your Java class file.

File Information

If you want to see something like this in your documentation

and clicking on the class name (not code) gives:

then you need to comment the top of your file like:

Namespace / Package Information

If you want to see something like this in your documentation

then you need to comment your package like this:

Class Attribute Documentation

If your class has some attributes/members then you’ll also want them to be documented like this:

So you’ll want to comment them like this:

Method Documentation

Well done, you made it to the important one!  Without doubt if you are doing this for a project you will need show commented code and if you want something like this

then you’ll need to comment like this:

You can also use things like:

• Inline double slash comments inside the method and if you have the correct configuration they will be included.  See my attached config file as an example.
• @return to specify a return parameter e.g. * @return true if we have reached the side 
• @see to link (with hyperlinks in the finished documentation) to other methods e.g. * @see Player.updateSensorLines();
• @todo which is a great way to create a todo list of things that you have to remember to go back and fix or to properly e.g    * @todo Stop the flickering costume when not moving.  Like any other pages you create they will be found under related pages.

EXTRA PAGES

Lastly you don’t really want a blank page as the homepage for your documentation so why not make that into your Installation/User Guide.   Create a page called mainpage.dox and place it into your src folder.  Set it up like this:

and it will create a mainpage like:

Or how about a development diary?

comes from a file called diary.dox that look like:

Hope you enjoy using Doxygen to document your code.