Using Comments For Documentation

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.

The following source code snippet contains java-style comments, with javadoc-style markup. Further, an embedded processing instruction wants some declarations to be grouped.

#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

        

The right combination of comment processing options for this code would be:

synopsis -p Cxx --cfilter=java --translate=javadoc -lComments.Grouper ...

The --cfilter option allows to specify a filter to select document comments, and the --translate option sets the kind of markup to expect. The -l option is somewhat more generic. It is a linker to which (almost) arbitrary post-processors can be attached. Here we pass the Comments.Grouper processor that injects Group nodes into the IR that cause the grouped declarations to be documented together.