The synopsis executable is a little convenience frontend to the larger Synopsis framework consisting of IR-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 semantic graph (ASG). 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 ASG 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 ASG, typically html, docbook xml, or class graphs. Other formatters exist to assist debugging, such as a List formatter that prints specific aspects of the IR to stdout, or a Dump formatter that writes the IR to an xml file, useful for unit testing.
You can run synopsis with a single processor, for example
to parse a C++ file source.hh
and store
the ASG 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 the most important 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.
Specify a comment filter (See the section called “Comment Filters”).
Translate comments to doc-strings, using the given markup specifier (See the section called “Comment Translators”).
Specify the directory under which to store SXR info for the parsed source files. This causes parsers to generate SXR info, the linker to generate an sxr Symbol Table, and for the HTML formatter this causes Source and XRef views to be generated.
This is useful in conjunction with the -p Cpp
option to probe
for system header search paths and system macro definitions. (See the section called “Emulating A Compiler”).