Developers breathe easier when Doxygen’s on the job

Coding programs can be a full-time job, leaving little time and energy for developers to document their source code – so why not have another program do it for you? Doxygen is a popular source code documentation tool that can generate an online documentation browser or an offline reference manual from a set of annotated source files. It can parse a range of programming languages – including C, C++, Java, Objective-C, C#, Python, PHP, and VHDL; generate output in a number of formats – including HTML, LaTeX, RTF, and man pages; and works on many platforms, including Windows, Mac OS X, and Linux.

Letting Doxygen generate documentation from annotated code keeps documentation consistent with the source code in a better way than maintaining a separate document. Doxygen is used by many open source projects and even more commercial projects all over the world; it’s localized in more than 30 languages. The largest user bases are in the US, Germany, and Japan, based on download statistics, according to project leader Dimitri van Heesch.

What makes Doxygen unique? Van Heesch says other documentation project alternatives typically handle only a single language or output format or require more markup commands to be useful. Doxygen also provides a structured view of the source code in the form of diagrams and cross-referenced and syntax-highlighted code – even if the code does not have any comments at all. The combination of powerful reverse architecting and documentation capabilities in a single easy-to-use tool makes Doxygen really stand out.

Doxygen began almost 13 years ago after van Heesch graduated from university. At that time the Qt library was in its early stages of development, and van Heesch wrote a table widget as an extension to the library. “The Qt library had beautifully cross-referenced documentation, but my widget had not,” he recalls. “After writing part of the documentation by hand, only to find out that it got out of sync with the code rather quickly, I started looking for a way to automate this.”

Van Heesch asked a Qt developer if there were plans to release that project’s documentation tool. (At the time there weren’t but with the acquisition of Qt by Nokia the tool was recently released as qdoc3.) He found DOC++, which was close to what he wanted, “but the look and capabilities were not good enough in my opinion, and it did not understand the Qt-specific language extensions. So I started coding something myself, taking some of the lexical scanning stuff from DOC++, as that was new to me. I soon realized that this would be useful for others working on Qt widgets as well, so I released it under the GNU Public License. I did not envision I would still work on it 13 years later!

“Doxygen is and has always been my hobby project. It touches quite different aspects of programming and software, and I have full freedom to do what I want, so it is not just more work.”

Although he develops on a MacBook Pro these days, van Heesch says he’s really “a command-line guy.
I always have a terminal or two open, and use all the typical GNU and open source tools, such as ls, sed, make, and gcc. For editing source code I use vim. One of the wonderful tools I miss from my Linux development days is Valgrind; it’s really helpful to find memory leaks, memory corruption, and performance bottlenecks.”

While Doxygen is adept at producing documentation, van Heesch characterizes the project’s own documentation as “rather terse.” Given that, he offers a few tips for users:

- You can extract unannotated code by setting EXTRACT_ALL to YES in the config file.
- Generate diagrams by setting HAVE_DOT to YES and installing the GraphViz package and message sequence charts using Mscgen.
- Try the graphical front end, called Doxywizard, to help configure and run Doxygen.
- You can use the information collected by Doxygen on other tools via Doxygen’s XML output (optionally in combination with the XML parser found in addon/doxmlparser).
- You can split a configuration file into a generic part and overrule certain settings in a specific config file.

Van Heesch has a few enhancements to consider for upcoming versions. “I’ll typically pick one or two that are often requested for a new release. Sometimes I get patches that implement a new features and merge them. Support for Verilog and Ruby are patches that are still in my inbox, for instance. One of the ideas I’m playing with is to enhance Doxygen with a comment system like you see for many blogs, allowing users to add additional documentation to items in a generated page from within the browser. I typically make three to four official releases per year, and each month a tested and tagged Subversion commit.

“I’m always looking for feedback and people to help with the project. I would really welcome a designer who can, for instance, improve the HTML output produced by Doxygen, or a technical writer who’d like to improve the manual. I like to be in control over the consistency and quality of the code, so it works best if people submit patches, which I then review and include. People can contact me directly or via the developer or user mailing lists.”

UCDetector reveals unnecessary Java code

In older programs that have been modified many times, sometimes code creeps in that is no longer executed, and which can be removed without affecting the way the program runs. Leaving that code in place makes programs hard to understand; new developers rightly question what it’s for. But finding such code can be tricky – unless you have a tool like UCDetector, an Eclipse plugin that finds unnecessary Java code.

UCDetector can flag public classes, methods, and fields that have no references and display them in the Eclipse Problems view. A developer might run UCDetector after refactoring to clean up code, or when starting to work on someone else’s code.

German developer Jörg Spieler created the utility back in 2007 because “I like to refactor and simplify code. Removing unused code makes it easier to understand programs.” UCDetector is itself built using Eclipse for Java and plugin development, while Spieler uses Inkscape to create and edit icons, and jEdit for all other kind of files.

Spieler says UCDetector checks for dangerous cases where searching references and deleting code may cause your program to fail. For example, searching references for a method that is overridden causes no search matches, but you can’t delete the method. You can find code used only by test, and produce XML, HTML, and text reports. The utility also lets you create a custom detection by using existing classes, and you can run UCDetector without Eclipse as an Apache Ant task.

Spieler says the software is pretty feature-complete. He plans only bug fixes and feature requests from the community in upcoming versions. “I welcome interesting ideas from the community to improve
UCDetector, or other ways to find unused code, or other ideas on how to use results of searching for references in Java.”

Old-school MissionX is a blast

When you have a passion for both Java programming and old-school videogames, what do you do when your school gives you a year to produce a project? If you’re Italian developer Federico Dossena, you whip up MissionX, an old-school 2-D space shooter inspired by games like Lifeforce on the Nintendo and Vanguard Ace on the PC.

Dossena says he programmed 100% of the game’s code and about 30% of its game engine. “I also helped my friends make the levels.” To create the game he used NetBeans (“because is the best IDE in my opinion”), the EasyWay game engine (“because I was working on it with a friend”), and the GIMP (“because it’s free”).

Since the year is now up and he had to turn in the project to his school, Dossena also released it on SourceForge as well. He says, “If I release the game as open source, someone might improve the code, make the game better, or just take a look at how I made things such as emitters, parallax effects, and so forth. I chose SourceForge because I wanted some visibility, so people will download the game, test it, and send me comments.”

MissionX may have just reached version 1.0, but Dossena and some of his friends are already developing two other games. “One is a platformer similar to Castlevania and the other is a kind of Arkanoid but with tons of cool weapons and powerups. This doesn’t mean that I’m not going to release other versions of MissionX; I’m actually planning a mod for this summer and a new version with improved Mac OS X support – though I need someone who can test it and compile a starter, because I don’t have a Mac. People will see the availability of a new version through the auto updater included in MissionX. If someone wants to help with development, they should just send me an e-mail and I’ll do my best to teach them how to use EasyWay and all the other stuff.”