A word about documentation

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 logo

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.

There are tons of projects using doxygen. SFML is just a C++ example.

Using doxygen is really simple. I’ll give you a 5 minute introduction to doxygen in the next post.

See you soon.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s