| about | news | docs | development |
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.
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.
The whole tool is be 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 be 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. UML is a nice example of meta types which could be used for this. |
|---|---|
| Support for pluggable parsers | A separate parser is used for each language. Users may install their own parser. 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 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 an abstract Formatter class which can be inherited from to define specific ways to output documentation. |
| 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. |