Parsing source code

As synopsis' current focus is on document generation, the AST it generates from a parsed source file consists of declarations only. Let's thus in the following consider how synopsis parses C++ header files.

Let's assume a simple header file, containing some declarations:

#ifndef _Path_h
#define _Path_h

//. A Vertex is a 2D point.
struct Vertex
{
  double x; //.< the x coordinate
  double y; //.< the y coordinate
};

//. Path is the basic abstraction
//. used for drawing (curved) paths.
class Path
{
public:
  virtual ~Path() {}
  //. Draw this path.
  virtual void draw() = 0;
  // temporarily commented out...
  // void intersects(const Path &);
private:
};

#endif

        

Process this with

synopsis -p Cxx -f HTML -o Paths Path.h

to generate an html document. As you will note, all declarations appear in the document, each associated with the comment(s) preceding it in the code. We used here a C++ header (and the associated Cxx parser), but we could equally well have chosen another supported language.

While this one-line command is convenient, it is usually better (and more clear) to separate the individual processing steps. We will now fine-tune the processing, demonstrating the flexibility of the processers.