<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Documenting Source-Code</title><link rel="stylesheet" href="synopsis.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Synopsis Tutorial" /><link rel="up" href="intro.html" title="Chapter 1. Introduction" /><link rel="prev" href="ir.html" title="Internal Representations" /><link rel="next" href="processing.html" title="The Synopsis Processing Pipeline" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Documenting Source-Code</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ir.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="processing.html">Next</a></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="documenting"></a>Documenting Source-Code</h2></div></div></div><p>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.</p><p>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 <span class="emphasis"><em>doc-strings</em></span>, in other languages ordinary
comments are used.</p><p>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).</p><div class="example"><a id="id490951"></a><p class="title"><b>Example 1.1. Typical C++ code documentation</b></p><div class="example-contents"><div class="caption"><p>C++ may contain a mix of comments, some representing documentation.
</p></div><pre class="screen">
//! A friendly function.
void greet()
{
// FIXME: Use gettext for i18n
std::cout << "hello world !" << std::endl;
}
</pre></div></div><br class="example-break" /><p>In Synopsis all declarations may be annotated. C and C++ parsers,
for example, will store comments preceding a given declaration in
that declaration's <code class="varname">annotations</code> dictionary under the
key <code class="constant">comments</code>. Later these comments may be translated
into documentation (stored under the key <code class="constant">doc</code>), which
may be formatted once the final document is generated.</p><p>Translating comments into doc-strings involves the removal of comment
markers (such as the <code class="code">//!</code> above), as well as the handling of
processing instructions that may be embedded in comments, too.</p><p>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.</p><div class="example"><a id="id490998"></a><p class="title"><b>Example 1.2. Python code documentation</b></p><div class="example-contents"><div class="caption"><p>Python has support for documentation built into the language.</p></div><pre class="screen">
>>> 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.
</pre></div></div><br class="example-break" /></div><div class="navfooter"><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ir.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="processing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Internal Representations </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> The Synopsis Processing Pipeline</td></tr></table></div></body></html>
