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.