1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using comments for documentation</title><link rel="stylesheet" href="synopsis.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="Synopsis Tutorial"><link rel="up" href="using.html" title="Chapter2.Using the synopsis tool"><link rel="previous" href="parsing.html" title="Parsing source code"><link rel="next" href="misc.html" title="Miscellaneous"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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="parsing.html">Prev</a></td><th width="60%" align="center">Chapter2.Using the synopsis tool</th><td width="20%" align="right"><a accesskey="n" href="misc.html">Next</a></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="comments"></a>Using comments for documentation</h2></div></div><div></div></div><p>The <tt class="filename">Path.h</tt> header contains different kinds of comments,
not all of which are intended to be used as documentation. Here we want
to preserve only those comments starting with '//.'. That's done with the
<span class="type">SSDFilter</span>(read: 'slash slash dot') processor. Further, the
members of the <span class="type">Vertex</span> strcture are commented <span class="emphasis"><em>after</em></span>
the declaration, with comments using the prefix '//.<'. These are dealt
with by the <span class="type">Previous</span> processor.</p><p>The result of
</p><pre class="programlisting">synopsis -p Cxx -l SSDFilter,Previous -o Path.syn Path.h
synopsis -f HTML -o Paths Path.syn
</pre><p>
looks already much better.
</p><p>Let us now add more input files:
</p><pre class="programlisting">#ifndef _Polyline_h
#define _Polyline_h
#include "Path.h"
#include <vector>
namespace Paths
{
// The Polyline class. It is an ordered set of
// connected line segments.
class Polyline : public Path
{
public:
// Create a new Polyline.
//
Polyline();
// @group Manipulators {
// Add a new vertex.
void add_vertex(const Vertex &);
// Remove the vertex at index i.
void remove_vertex(size_t i);
// }
virtual void draw();
private:
// The data...
std::vector<Vertex> _vertices;
};
}
#endif
</pre><p>
This header uses a different comment convention. Here relevant comments
start with '//', so we will use the <span class="type">SSFilter</span> Processor.
Additionally, it uses special tags to group declarations together. As there
is more than one possible grouping syntax, we will use the <span class="type">Grouper1</span>
processor (and discuss the others in <a href="scripting.html" title="Chapter3.Scripting and extending synopsis">Chapter3, <i>Scripting and extending synopsis</i></a>):
</p><pre class="programlisting">synopsis -p Cxx -l SSFilter,Grouper1 -o Polyline.syn Polyline.h
synopsis -f HTML -o Paths Path.syn Polyline.syn
</pre><p>
</p><p>Finally, let us look at a header file that is written in javadoc style,
i.e. with java-style comments, and containing special tags:
</p><pre class="programlisting">#ifndef _Nurbs_h
#define _Nurbs_h
#include "Path.h"
#include <vector>
namespace Paths
{
/**
* The Nurbs class. It implements a nurbs curve
* for the given order. It is a very powerful
* and flexible curve representation. For simpler
* cases you may prefer to use a @see Bezier curve.
*/
template <size_t Order>
class Nurbs : public Path
{
public:
/**
* Create a new Nurbs curve.
*/
Nurbs();
/**
* Inserts a control point with the given weight.
* The knot value determines the position in the sequence.
* @param knot the parameter value at which to insert a new knot
* @param vertex the control point
* @param weight the weight of the control point
*/
void insert_control_point(double knot, const Vertex &vertex,
double weight);
virtual void draw();
private:
/**
* The data...
*/
std::vector<Vertex> _controls;
std::vector<double> _weights;
std::vector<double> _knots;
};
}
#endif
</pre><p>
Here, we filter out undesired comments with the <span class="type">JavaFilter</span>
processor, and then parse the comments for @tags with <span class="type">JavaTags</span>:
</p><pre class="programlisting">synopsis -p Cxx -l JavaFilter,JavaTags -o Nurbs.syn Nurbs.h
</pre><p>
Finally, we generate the documentation with all the headers together, with the
additional <tt class="option">--javadoc</tt> flag that tells the HTML formatter to
include a <span class="type">Javadoc</span> comment processor to generate appropriate links
and other formatting.
</p><pre class="programlisting">synopsis -f HTML --javadoc -o Paths Path.syn Polyline.syn Bezier.syn Nurbs.syn
</pre><p>
</p><p>The full code together with the Makefile can be found <a href="examples/Paths" target="_top">here</a>
</p></div><div class="navfooter"><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parsing.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="misc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Parsing source code</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Miscellaneous</td></tr></table></div></body></html>
|
