The synopsis executable

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:

Parser

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.

Linker

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.

Formatter

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:

-h, --help,

print out help message

-V, --version,

print out version info and exit

-v, --verbose,

operate verbosely

-d, --debug,

operate in debug mode

-o, --output,

output file / directory

-p, --parser,

select a parser

-l, --link,

link

-f, --formatter,

select a formatter

-I

set an include search path

-D

specify a macro for the parser

-W

pass down additional arguments to a processor. For example '-Wp,-I.' sends the '-I.' option to the parser.