Synopsis is a tool for creating documentation from source code, using both comments and the code itself - the code is actually parsed rather than just searching for comments and particular expressions. Currently Synopsis can parse C++, Python and CORBA IDL, and generate documentation in a range of formats including HTML, DocBook, PDF and Dia graphs.

There are three stages in the documentation process: Parsing, Linking and Formatting. The data passed between each stage is an AST (Abstract Syntax Tree), a rich data structure which reflects the structure of the program. All three stages can be executed at once, or the AST can be stored to disk for later use.

Parsing is performed by language-specific parser modules. The most advanced is the C++ parser which does correct name resolution and generates extra information used to syntax highlight the source code and cross-reference symbols.

The Linking stage is where Synopsis derives most of its power, performing complex manipulations of the AST. At a minimum it handles the merging of multiple ASTs, eg: from different source files. It can manipulate the AST based on comments in the source, or perform things like renaming declarations to, for example, link directly to an IDL interface instead of a CORBA stub/skeleton.

The Formatting stage generates the documentation from the AST output by the Linking stage. There are a number of modules, but the most common is the HTML module. The HTML formatter is very flexible, itself consisting of multiple "Page" modules each of which generates a part of the documentation (the index, the list of modules, the class documentation, the inheritance tree, etc.)

Synopsis was written by Stephen Davies (aka Chalky) and Stefan Seefeld.

This manual was written by Stephen Davies.