Providing documentation for your source code is a must. It becomes even more crucial if you develop APIs used by other software engineers. When I say APIs I refer to libraries, frameworks written in C++ and other languages such as Python within the context of this article.
I can hear many of you saying “I comment my code, so what?”. Well imagine if there was no HTML documentation of Qt Framework and likewise there was no HTML documentation of Maya API. Would you like the idea of digging into the header/source files to see the documentation/comments?
This is why HTML documentation exists. So developers can find what they need, check the references, read them through, see the examples if any, without loosing time on something ridiculous like trying to understand how things really work in any given API. After all, software engineers should spend their precious time on more productive activities, like writing well architected, efficient, easy to read code in order to make software development robust and enjoyable.
Needless to say there are tools, which automatically generates HTML documentation based on the documentation available in source code. One of them is Sphinx and you probably already heard about it particularly if you are a Python developer.
Sphinx requires Python modules, which the documentation will be created for, to be in PYTHONPATH since it reads docstrings. This is an issue when you want to generate documentation for source code that imports third party modules like maya.cmds. Generating documentation becomes problematic in such cases due to third party modules being only available within the context of the applications (DCCs) where they meant to be used in. We usually use shell to invoke commands or develop purpose-built APIs to automate generating documentation, mostly outside of the scope of any applications (DCCs). If you think that this problem can easily be fixed by introducing a try/except block for imports please stop reading this article right now.
And there is Doxygen, which is my favorite. Unlike Sphinx, Doxygen parses the source code. Thus, there is no exception for “unavailable” modules for obvious reason. It also supports many languages (C, C++, C#, Fortran, Java, Objective-C, etc.) out of the box. It’s been around for long time and almost has “arguably” become the “standard” in C++ world as well. For instance, Maya API Reference is generated by Doxygen.
I use Doxygen over others because of an important concept called “consistency“. If you follow me for a while you must have an idea how serious I am when it comes to things like “consistency” and “productivity“.
All the programming languages I use are supported by Doxygen and regardless of the language, the documentation tags/style and the generated HTML documentations are consistent.
Doxygen also provides concise “overview” sections where you can see all the methods, properties, etc. and brief explanations about them, like shown in the example below.
I can hear someone saying “It’s just templating, it can bee added to other documentation tools as well”. You know what? That someone would absolutely be right! Of course it can be added to any other tool. So I am gonna let that “someone” to be my guest to do it.
The screenshot above shows a document (you can see it live at https://meco.api.safakoner.com), which has been generated from Python source code. The one below on the other hand has been generated from C++ source code.
Wouldn’t it be awesome to benefit from such consistency, particularly considering VFX, animation and game development sectors, where C++ and Python (I can even include C#) are the mostly used programming languages?
So you learn how to document your code once and use it in pretty much any other programming languages you can imagine of. Do I even need to write about benefits of having such consistency?
I value my time a lot because it’s something I can’t buy back. I always want to work productively. I do not want to deal with chores like editing templates, providing “additional” code, adding paths just to be able to generate documentation, let alone learning redundant skills. There are far more flexible, productive and consistent ways of doing things, and I promote them furiously.
So maybe you should stop being “politically correct” and take a look at Doxygen to see how it may benefit you…
