We all know information is priceless. Whether we’re trying to find out how maglev trains work, or why there exist such a thing as the laplace transform, or even simplier: how to add friends in facebook. We always look for information.
In informatics, it is not different, programmers need to know how a program works before updating it, fixing it or adding new functions. Documenting software is not an easy task. Documenting is a way of describing how “your baby” should be used. Why it shouldn’t be used in certain cases and how it works.
When documenting c/c++ small software projects you could use the copy-paste approach, where you copy and paste the function definitions and explain in a “word processing document” how your function/file/module works. The disadvantage: evolution. Code is not static and it is not meant to be this way. “Documents” made this way will become obsolet sooner or later, it’s just a question of time.
Another approach is to document code directly in the source code. This implies, however, the reader has already a good knowledge of the software: how its organized and how it is used. This is not always easy as “learning how this works” is the purpose of reading a documentation. That’s where automators enter the game field.
Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D. Doxygen is a must have :
- It can generate documentation in many formats such as html, pdf and latex.
- It is largely configurable.
Using doxygen is really simple. I’ll give you a 5 minute introduction to doxygen in the next post.
See you soon.