Documenting Source-Code

Being read and understood is at least as important for source code as it is for it to be processed by a computer. Humans have to maintain the code, i.e. fix bugs, add features, etc.

Therefor, typically, code is annotated in some form in that adds explanation if it isn't self-explanatory. While comments are often used to simply disable the execution of a particular chunk of code, some comments are specifically addressed at readers to explain what the surrounding code does. While some languages (e.g. Python) have built-in support for doc-strings, in other languages ordinary comments are used.

Typically, comments are marked up in a specific way to discriminate documentation from ordinary comments. Further the content of such comments may contain markup for a particular formatting (say, embedded HTML).

Example 1.1. Typical C++ code documentation

C++ may contain a mix of comments, some representing documentation.

//! A friendly function.
void greet()
  // FIXME: Use gettext for i18n
  std::cout << "hello world !" << std::endl;

In Synopsis all declarations may be annotated. C and C++ parsers, for example, will store comments preceding a given declaration in that declaration's annotations dictionary under the key comments. Later these comments may be translated into documentation (stored under the key doc), which may be formatted once the final document is generated.

Translating comments into doc-strings involves the removal of comment markers (such as the //! above), as well as the handling of processing instructions that may be embedded in comments, too.

For languages such as Python such a translation isn't necessary, as the language has built-in support for documentation, and thus the parser itself can generate the 'doc' annotations.

Example 1.2. Python code documentation

Python has support for documentation built into the language.

>>> def greet():
...     """The greet function prints out a famous message."""
...     print 'hello world !'

Help on function greet in module __main__:

    The greet function prints out a famous message.