|
Latest News:
September 24, 2003: We've moved.SynopsisSynopsis 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. GoalsThe 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. SolutionsThe 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 languagesThe 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 parsersA 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 manipulationsThe 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 formattersUsers 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. |