Diving into Doxygen: Documenting for Devs, Teammates, and AIs

#ai #gamedev #documentation #productivity

Ah, code documentation. That one thing we all love when we need it, but when it's time to actually write it... it can be a drag, right?

If you've ever worked on a team, you know how crucial good documentation is. It avoids the classic "hey, how do I use this function of yours?" and makes onboarding a new dev a much less painful experience. But what about when it's a solo project? Trust me, your "future self" will be immensely grateful for not having to decipher code that you wrote six months ago.

A quick note before we dive in: I originally drafted this post a few months ago, and in that short time, the world of coding has been completely shaken up by AI assistants. You might think that with tools like Copilot writing code for us, old-school practices like documentation are becoming obsolete. But I've found it's exactly the opposite. These fundamentals are now more important than ever. Think of it this way: good documentation is what trains your AI assistant to be a useful partner, not just a random code generator.

As Harold Abelson once said:

"Programs must be written for people to read, and only incidentally for machines to execute."

It's the absolute truth. But lately, that quote has gotten a modern upgrade. Today, besides your team and your future self, there's a new "reader" for your code: Artificial Intelligence. Tools like Copilot and other generative AIs have become our new, omnipresent interns, and well-documented code is what guides them to provide truly useful suggestions.

The Philosophy: Why Bother? The Classic Benefits (and the New AI Bonus)

When I think about code structure, the K.I.S.S. principle (Keep It Simple, Stupid!), a concept I've recently come to appreciate, always comes to mind. Code that is direct, predictable, and has clearly defined responsibilities isn't just more elegant; it's infinitely easier to maintain and, of course, to document.

In my opinion, this is even more valuable in game development. Imagine a single function that handles collision, applies damage, updates the UI, and plays a sound, all at once. That's a nightmare to maintain. It quickly becomes a house of cards, with everything tangled and dependent on everything else.

Combining simple code with a great documentation tool like Doxygen offers incredible advantages:

📑 It standardizes your documentation: Creates a consistent pattern that the entire team (and AIs) can follow.
🤝 It makes collaboration easier: Reduces the need to ask obvious questions and speeds up development.
🤖 It supercharges your AI: Clear comments and tags (@param, @return) are fuel for AIs. They use these "magic words" to understand the intent of your code and generate much more intelligent and accurate suggestions.
🛠️ It generates professional output: Automatically transforms your comments into a navigable HTML website or a PDF.

And yeah, I also think it's a bit sci-fi to be writing for an AI, but it's our new, and increasingly real, reality.

We let the AI handle the boring and heavy work while we enjoy a little time travel.

Doxygen: The Magic of Turning Comments into Docs

Doxygen generates documentation from comments you write directly in your code. While it's a powerhouse in the C/C++ world, it also supports many other languages.

The "magic" happens with special comment blocks. Check out this C++ example:

/**
 * @brief Calculates the final damage to be applied to a target.
 *
 * It takes the target's defense and the possibility of a critical hit into account.
 *
 * @param baseDamage The base damage of the weapon or skill.
 * @param targetDefense The target's defense value.
 * @param isCritical A boolean indicating if the hit was critical.
 * @return The final calculated damage.
 */
int CalculateDamage(int baseDamage, int targetDefense, bool isCritical);

Commands like @brief, @param, and @return are "tags" that Doxygen understands and uses to structure the documentation.

Getting Your Hands Dirty: Your First Steps

Want to get started? Using Doxygen from the command line is pretty simple:

Generate the config file: In your terminal, navigate to your project's folder and run doxygen -g. This will create a configuration file named Doxyfile, which contains tons of customizable options to define how you want your documentation to look.
Generate the documentation: After tweaking the Doxyfile (at least to point to your source code folder and an output folder), just run doxygen Doxyfile.

And that's it! A folder containing a navigable HTML site of your documentation will be created.

Doxyfile configuration file generated with doxygen -s -g

If you don't like the idea of editing the huge (and intimidating) Doxyfile by hand, there's also DoxyWizard, a graphical user interface that makes the configuration process much easier.

Not Just for C++: Documentation in the Game Dev World

This philosophy of in-code documentation isn't exclusive to Doxygen. Our favorite game engines already have built-in mechanisms for this:

In GameMaker, the community widely uses the JSDoc standard. By using tags like @description and @param, you can create tooltips and other useful info that pops up right in the IDE when you hover over a function. Link to GameMaker Docs

In Godot, it's even more integrated. GDScript comments starting with ## are treated as documentation and are displayed in the editor's help panel. They even support BBCode for formatting, like [b] for bold and [codeblock] for code examples. Link to Godot Docs

This just goes to show that, no matter the tool, the practice is universally powerful.

So, What Now?

Documenting your code doesn't have to be a headache. With the right tools and a bit of discipline, we can turn a tedious task into a valuable investment for the future of our projects—whether it's for our team, our future selves, or even the AI that's helping us code.

I'm currently exploring the best way to integrate Doxygen-generated documentation with GitHub Pages to make it all accessible online automatically. Once I have a solid workflow, I promise I'll be back with a new post to share the details. 😉

Until then, why not take a look at your own projects and see where a little documentation could make a big difference? I'm always looking to improve my workflow, especially with AI, so if you've found a better way to do this, let me know over on [LinkedIn/X]! I'd love to learn from your experience. 🚀