<?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>Comment Processors</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="processors.html" title="Chapter 4. Processor Design" /><link rel="prev" href="linker.html" title="The Linker" /><link rel="next" href="dump-formatter.html" title="The Dump Formatter" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Comment Processors</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="linker.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Processor Design</th><td width="20%" align="right"> <a accesskey="n" href="dump-formatter.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="comment-processors"></a>Comment Processors</h2></div></div></div><p>Comments are used mainly to annotate source code. These annotations may
consist of documentaton, or may contain processing instructions, to be parsed
by tools such as Synopsis.</p><p>Processing comments thus involves filtering out the relevant comments, parsing
their content and translating it into proper documentation strings, or otherwise perform
required actions (such as ASG transformations).</p><p>Here are some examples, illustrating a possible comment-processing pipeline.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="comment-filters"></a>Comment Filters</h3></div></div></div><p>To distinguish comments containing documentation, it is advisable to use
some convention such as using a particular prefix:</p><pre class="programlisting">
//. Normalize a string.
std::string normalize(std::string const &);
// float const pi;
//. Compute an area.
float area(float radius);
</pre><p>Using the <code class="constant">ssd</code>(read: Slash-Slash-Dot) prefix filter
instructs Synopsis only to preserve those comments that are prefixed with
<code class="code">//.</code></p><pre class="screen">synopsis -p Cxx --cfilter=ssd ...</pre><p>Synopsis provides a number of built-in comment filters for frequent / popular
prefixes. Here are some examples:</p><div class="segmentedlist"><table border="0"><thead><tr class="segtitle"><th>Comment prefix</th><th>Filter class</th><th>option name </th></tr></thead><tbody><tr class="seglistitem"><td class="seg">//</td><td class="seg">SSFilter</td><td class="seg">ss</td></tr><tr class="seglistitem"><td class="seg">///</td><td class="seg">SSSFilter</td><td class="seg">sss</td></tr><tr class="seglistitem"><td class="seg">//.</td><td class="seg">SSDFilter</td><td class="seg">ssd</td></tr><tr class="seglistitem"><td class="seg">/*...*/</td><td class="seg">CFilter</td><td class="seg">c</td></tr><tr class="seglistitem"><td class="seg">/*!...*/</td><td class="seg">QtFilter</td><td class="seg">qt</td></tr><tr class="seglistitem"><td class="seg">/**...*/</td><td class="seg">JavaFilter</td><td class="seg">java</td></tr></tbody></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="comment-translators"></a>Comment Translators</h3></div></div></div><p>Once all irrelevant comments have been stripped off, the remainder needs to be
transformed into proper documentation. As the actual formatting can only be performed
during formatting (at which time the output medium and format is known), there are still
things that can be done at this time: Since in general it isn't possible to auto-detect
what kind of markup is used, a translator assists in mapping stripped comment strings to
doc-strings, to which a <code class="varname">markup</code> specifier is attached. While this specifier
is arbitrary, the only two values supported by the HTML and DocBook formatters are
<code class="varname">javadoc</code> and <code class="varname">rst</code>(for ReStructuredText).</p><p>Note that this comment translation is specific to some programming languages
(such as C, C++, and IDL). Notably Python does provide a built-in facility to associate
doc-strings to declarations. (In addition, the doc-string markup can be expressed via
special-purpose variable <code class="varname">__docformat__</code> embedded into Python source code.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="comment-transformers"></a>Transformers</h3></div></div></div><p>In addition to the manipulation of the comments themselves, there are actions that may
be performed as a result of <span class="emphasis"><em>processing-instructions</em></span> embedded into comments.
</p><p>For example, A <span class="type">Grouper</span> transformer groups declarations together, based on
special syntax:</p><pre class="programlisting">
/** @group Manipulators {*/
/**
* Add a new control point.
* @param p A point
*/
void add_control_point(const Vertex &);
/**
* Remove the control point at index i.
* @param i An index
*/
void remove_control_point(size_t i);
/** }*/
virtual void draw();
</pre><p>To process the above <code class="code">@group</code> processing-instruction,
run <strong class="userinput"><code>synopsis -p Cxx --cfilter=java -l Grouper ...</code></strong></p></div></div><div class="navfooter"><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="linker.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="processors.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dump-formatter.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">The Linker </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> The Dump Formatter</td></tr></table></div></body></html>
