Javadoc

Synopsis provides support for Javadoc-style markup (See http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html). However, as Javadoc is very HTML-centric, best results will only be achieved when HTML is the only output-medium.

Javadoc comments consist of a main description, followed by tag blocks. Tag blocks are of the form @tag. The following block tags are recognized:

author, date, deprecated, exception, invariant, keyword, param, postcondition, precondition, return, see, throws, version

All blocks may contain any of the following inline tags, which are of the form {@inlinetag}:

link, code, literal

Link targets may be text, or HTML anchor elements. In case of text Synopsis interprets the it as a name-id and attempts to look it up in its symbol table.

All of the above tags are recognized and translated properly for both, the HTML as well as the DocBook formatters. Javadoc recommends to use HTML markup for additional document annotation. This is only supported with the HTML formatter, however.

Example C.1. C++ code snippet using Javadoc-style comments.

/**
 * The Bezier class. It implements a Bezier curve
 * for the given order. See {@link Nurbs} for an alternative
 * curved path class. Example usage of the Bezier class:
 * <pre>
 *   Bezier&lt;2&gt; bezier;
 *   bezier.add_control_point(Vertex(0., 0.));
 *   bezier.add_control_point(Vertex(0., 1.));
 *   ...
 * </pre>
 *
 * @param Order The order of the Bezier class.
 * @see <a href="http://en.wikipedia.org/wiki/Bezier"/>
 */
template <size_t Order>
class Bezier : public Path
{
...