<?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>Using Comments For Documentation</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="using.html" title="Chapter 2. Using the synopsis tool" /><link rel="prev" href="compiler-emulation.html" title="Emulating A Compiler" /><link rel="next" href="scripting.html" title="Chapter 3. Scripting And Extending Synopsis" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using Comments For Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="compiler-emulation.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the synopsis tool</th><td width="20%" align="right"> <a accesskey="n" href="scripting.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="comments"></a>Using Comments For Documentation</h2></div></div></div><p>Until now the generated document didn't contain any of the text from
comments in the source code. To do that the comments have to be translated
first. This translation consists of a filter that picks up a particular kind
of comment, for example only lines starting with "//.", or javadoc-style
comments such as "/**...*/", as well as some translator that converts the
comments into actual documentation, possibly using some inline markup, such
as Javadoc or ReST.</p><p>The following source code snippet contains java-style comments, with
javadoc-style markup. Further, an embedded processing instruction wants some
declarations to be grouped.
</p><pre class="programlisting">#ifndef Bezier_h_
#define Bezier_h_
#include "Path.h"
#include <vector>
namespace Paths
{
/**
* The Bezier class. It implements a Bezier curve
* for the given order.
*/
template <size_t Order>
class Bezier : public Path
{
public:
/** Create a new Bezier.*/
Bezier();
/** @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();
private:
/** The data...*/
std::vector<Vertex> controls_;
};
}
#endif
</pre><p>
</p><p>
The right combination of comment processing options for this code would be:
</p><pre class="programlisting">synopsis -p Cxx --cfilter=java --translate=javadoc -lComments.Grouper ...</pre><p>
The <code class="option">--cfilter</code> option allows to specify a filter to select
document comments, and the <code class="option">--translate</code> option sets the kind of markup
to expect. The <code class="option">-l</code> option is somewhat more generic. It is a <span class="emphasis"><em>linker</em></span>
to which (almost) arbitrary post-processors can be attached. Here we pass the <span class="type">Comments.Grouper</span>
processor that injects <span class="type">Group</span> nodes into the IR that cause the grouped declarations to
be documented together.
</p></div><div class="navfooter"><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="compiler-emulation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="scripting.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Emulating A Compiler </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Scripting And Extending Synopsis</td></tr></table></div></body></html>
