Synopsis - Home

Synopsis

Synopsis is a general source code documentation tool. By means of a modular structure it adapts to different styles of embedded documentation, different programming languages and various output formats. It scales well with the size of the project by allowing processing to be controlled by Makefiles.

Goals

The original goal of this project was to be able to generate a reference manual for a project we are working on which uses different programming lanugages: the protocols are defined with IDL and the implementation is written in C++. There are no tools to support document generation with explicit cross references between both parts. When thinking about how to design a tool which is able to do that, it was quickly concluded that other parts could be 'outsourced' into separate modules as well, such as the formatting of the generated syntax tree. These are a couple of ideas which hopefully make it a tool which is useful in a wide range of projects.

Solutions

The whole tool is factored into three parts to make extensibility easy and to keep the total size to a minimum depending on the user's requirements:

Support for multiple languages

The syntax tree which is the backbone of the tool is designed with this in mind. Individual types need to be sufficiently abstract so they can hold a variety of concrete types depending on the language.

Support for pluggable parsers

A separate parser is used for each language. The parser generates an abstract syntax tree (AST) which represents the structure of the source code in a language-independant manner. Associated with each node is the document or comment which the parser finds close to the type declaration. This documentation is stripped of the language specific prefix (like '//' in C++, '#' in Python etc.) and stored as a string.

Support for complex manipulations

The AST can be modified by a series of modules to perform different tasks suited to the user's requirements for documentation and the usage of comments in source code. For example, different languages can be linked together (e.g.: CORBA IDL to C++), and comments can be examined to group similar declarations.

Support for pluggable formatters

Users have very different requirements for the formatting style so Synopsis does not impose any particular output or comment format. With an AST as described above it's easy to write a custom formatter to generate output as required. A number of formatters are in included, including a very flexible and extensible HTML formatter.

Scalable to different project sizes

The size of the project, i.e. the number of files to parse may vary a lot. It is desirable to be able to run Synopsis once if only a small number of files needs to be read. On the other hand, for larger numbers the AST is stored so that the 'make' tool can determine which part of the docs to regenerate if a source file was modified.
An new configuration method is under development which provides an alternative to Make by allowing Synopsis to figure out dependencies and rebuild changed parts of the AST automatically. This will complement a GUI in the future.