The synopsis executable is a little convenience frontend to the larger Synopsis framework consisting of AST related types as well as processor classes.
While the full power of synopsis is available through scripting (see Chapter 3, Scripting and extending synopsis), it is possible to quickly generate simple documentation by means of an easy-to-use executable, that is nothing more but a little script with some extra command line argument parsing.
This tool has three processor types it can call:
A processor that will parse source code into an internal abstract syntax tree (AST). Various Parsers have a variety of parameters to control how exactly they do that.
A processor that will remove duplicate symbols, forward declarations, and apply any number of AST manipulations you want. The user typically specifies what sub-processors to load to run from the linker.
A processor that generates some form of formatted output from an existing AST, typically html, docbook xml, or class graphs.
You can run synopsis with a single processor, for example to parse a C++ file source.hh and store the AST into a file source.syn, or you can combine it directly with linker and or formatter to generate the output you want in a single call.
While the document generation in a single call is convenient, for larger projects it is much more sensible to integrate the document generation into existing build systems and let the build system itself manage the dependencies between the intermediate files and the source files.
For example, a typical Makefile fragment that contains the rules to generate documentation out of multiple source files may look like this:
hdr := $(wildcard *.h) syn := $(patsubst %.h, %.syn, $(hdr)) html: $(syn) synopsis -f HTML -o $@ $< %.syn: %.h synopsis -p Cxx -I../include -o $@ $<
Here is a listing of all available options:
print out help message
print out version info and exit
operate verbosely
operate in debug mode
output file / directory
select a parser
link
select a formatter
set an include search path
specify a macro for the parser
pass down additional arguments to a processor. For example '-Wp,-I.' sends the '-I.' option to the parser.