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.
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 prefix | Filter class | option name |
---|---|---|
// | SSFilter | ss |
/// | SSSFilter | sss |
//. | SSDFilter | ssd |
/*...*/ | CFilter | c |
/*!...*/ | QtFilter | qt |
/**...*/ | JavaFilter | java |
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.
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 ...