Comment Processors

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.

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).

Here are some examples, illustrating a possible comment-processing pipeline.

Comment Filters

To distinguish comments containing documentation, it is advisable to use some convention such as using a particular prefix:

//. Normalize a string.
std::string normalize(std::string const &);
// float const pi;
//. Compute an area.
float area(float radius);
        

Using the ssd(read: Slash-Slash-Dot) prefix filter instructs Synopsis only to preserve those comments that are prefixed with //.

synopsis -p Cxx --cfilter=ssd ...

Synopsis provides a number of built-in comment filters for frequent / popular prefixes. Here are some examples:

Comment prefixFilter classoption name
//SSFilterss
///SSSFiltersss
//.SSDFilterssd
/*...*/CFilterc
/*!...*/QtFilterqt
/**...*/JavaFilterjava

Comment Translators

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 markup specifier is attached. While this specifier is arbitrary, the only two values supported by the HTML and DocBook formatters are javadoc and rst(for ReStructuredText).

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 __docformat__ embedded into Python source code.

Transformers

In addition to the manipulation of the comments themselves, there are actions that may be performed as a result of processing-instructions embedded into comments.

For example, A Grouper transformer groups declarations together, based on special syntax:

  /** @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();
        

To process the above @group processing-instruction, run synopsis -p Cxx --cfilter=java -l Grouper ...