Documenting Source-Code
Prev | Chapter 1. Introduction | Next

## 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(greet)

    Help on function greet in module __main__:

    greet()
        The greet function prints out a famous message.

Prev | Up | Next
Internal Representations | Home | The Synopsis Processing Pipeline