The Path.h 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 SSDFilter(read: 'slash slash dot') processor. Further, the members of the Vertex strcture are commented after the declaration, with comments using the prefix '//.<'. These are dealt with by the Previous processor.
The result of
synopsis -p Cxx -l SSDFilter,Previous -o Path.syn Path.h synopsis -f HTML -o Paths Path.syn
looks already much better.
Let us now add more input files:
#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
This header uses a different comment convention. Here relevant comments start with '//', so we will use the SSFilter Processor. Additionally, it uses special tags to group declarations together. As there is more than one possible grouping syntax, we will use the Grouper1 processor (and discuss the others in Chapter 3, Scripting and extending synopsis):
synopsis -p Cxx -l SSFilter,Grouper1 -o Polyline.syn Polyline.h synopsis -f HTML -o Paths Path.syn Polyline.syn
Finally, let us look at a header file that is written in javadoc style, i.e. with java-style comments, and containing special tags:
#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
Here, we filter out undesired comments with the JavaFilter processor, and then parse the comments for @tags with JavaTags:
synopsis -p Cxx -l JavaFilter,JavaTags -o Nurbs.syn Nurbs.h
Finally, we generate the documentation with all the headers together, with the additional --javadoc flag that tells the HTML formatter to include a Javadoc comment processor to generate appropriate links and other formatting.
synopsis -f HTML --javadoc -o Paths Path.syn Polyline.syn Bezier.syn Nurbs.syn
The full code together with the Makefile can be found here