A couple of weeks ago I took time off work to relax. My intent was to focus my free time to further the development of the engine. However, I was feeling a bit burnt out and opted for documenting the engine instead. I figured it was going to be a breeze and not too mentally demanding. I was wrong. Very wrong.
Throughout the engine development, I had put aside documenting the source code. Hundreds of functions were not documented. Of course, I had given descriptive names to every function, but none of them had proper documentation.
Books and developers suggest documenting your code since the beginning of the project. They urge you not to put it until the end. I started doing so, but I stopped. I was trying to figure out how to develop a game engine. And as to be expected, my source code was constantly changing. So it became unproductive to spend time documenting it. After three years of development, I found myself with 106 files to document. Each file containing a dozen or so functions.
I wish someone would have told me how mentally demanding documenting code is. I am so burnt out that it has been two weeks since I wrote a single line of code.
Nonetheless, documenting would have been a lot more demanding without the following tools: VVdocumenter and Doxygen.
Let me explain what they do.
VVdocumenter
VVDocumenter is a Xcode plug-in that helps you write documentation comments. It not only works on Objective-C and Swift projects but also in C++ projects. By typing "///" before a function prototype, VVDocumenter extracts the function's parameters and return values. Here is an image that shows what VVDocumenter does.
Doxygen
Doxygen is a documentation generator for C++ projects. It is a powerful tool that makes documenting your source code a bit easier. Doxygen generates an on-line documentation from a set of documented source files, as shown below:
I love Doxygen, but I hate the on-line visual documentation it generates. Luckily, the tool allows custom CSS files which can be used to change the presentation of your documentation as shown below:
Documenting source code is annoying but is one of the most important tasks in software development. I used the tools above, and they helped me a lot. I hope they are also helpful to you.
