Documentation [Easy Mode]

I’ve talked about AtomineerUtils before on my blog very briefly several months back when I first discovered it.  I’ve now been using it pretty much straight since then and I can’t live without it at this point.

So what does it do?

It takes an educated guess at what your method does based on the method name, return type and parameters and inserts a pretty good stub of documentation to get you started.

Think about it… if you write Doxygen style comments in your code, how much time do you lose to just formatting and tagging each parameter and then repeatedly copying and pasting the same description over and over for parameters that are basically self explanatory?

The current version lets your organization share the same preference files so you can all share the same rules to assist the tool generate the first stab at documenting your code.  The files that allow you to control the documentation generation are VERY customizable, my favorite feature is word expansion.  Which allows it to look for patterns in variables or method names like “MS” and expand them to “milliseconds” in the documentation.

I whipped together some examples to show you what it produces out of the box…

Before:

int GetTimeInMS(); void SendPlayerDeathMsg(Player player, const char* howPlayerDied, const char* wherePlayerDied);

After:

/* * @brief Gets the time in milliseconds. * * @return The time in milliseconds. / int GetTimeInMS(); / * @brief Sends a player death message. * * @param player The player. * @param howPlayerDied Describes how player died. * @param wherePlayerDied The where player died. */ void SendPlayerDeathMsg(Player player, const char* howPlayerDied, const char* wherePlayerDied);

It has a tool menu button you can use for generating the documentation, but I prefer to bind it to a key, makes it a lot easier to use. Here are the steps if you don’t know how.

Go to Tools > Customize
Customize
Click on Keyboard… in the bottom left and you can setup a key binding to the AddDocComment action, personally I use Ctrl+D.  All you need to do then to generate the doc block is have your cursor just above or on the method or class you want documented and just hit Ctrl+D.
Keyboard
Remember though, this is not a replacement for writing actual documentation. Don’t let yourself get into the habit of hitting Ctrl+D and moving on. AtomineerUtils will get you started, but you still need to verify and improve its results. If you find yourself correcting the same stuff over and over though, try creating a rule for it. Happy documenting.