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.