Much of the documentation of the implementation is contained in the interface files of the source code.
%TODO: make a graph illustrating the workflow.

Some notes:
\begin{itemize}
\item See \texttt{spgen/source/README.md} for a broad overview of the workflow and dependencies, read \texttt{spgen/source/spgen.ml} for the driver of the program.
%\item Terminology: patch rule, context rule, */+/- rule, context\_mode ...
\item Several of the modules make extensive use of the AST0 visitor\footnote{\texttt{coccinelle/parsing\_cocci/visitor\_ast0.ml}}. It is used because it abstracts away a lot of the boilerplace code needed for accessing the components of the abstract syntax tree.
\item An easy way to debug in \texttt{spgen/source/rule\_body.ml}: add
\begin{verbatim}
>> Snapshot.add "debug message" >>
\end{verbatim}
in some function sequence. Then "debug message" will appear in the exact same place it was called in the generated script.
\item Absolutely not optimised for performance (in particular, memory).

  \begin{itemize}
  \item Snapshot need not be purely functional; rule map can be hashtable in mutable record field instead of map (needs to be sorted in get\_result however). However, a map might be beneficial later on if we want to keep various copies for e.g. rule splitting.
  \item Rule map is converted to string list before printing; no need to do so, could just print directly from rule map. However, this makes for a better separation interface-wise.
  \item Most importantly, the generally small size of Coccinelle scripts means that performance is not actually a problem in practice.
  \end{itemize}

\item spgen needs its own flag in the Coccinelle parser: \texttt{Flag\_parsing\_cocci.generating\_mode}. This ensures that dependencies are not optimised away in the parser, as we need that information for printing the rules properly.

It cannot be substituted for the \texttt{ignore\_patch\_or\_match} option, because that option also affects other parts of the parser.
\item Regression tests: run spgen with flag \texttt{-{}-test <path\_to\_test\_dir} to run the tests. They should be run once before changing anything in the code. The tests test diff equality with expected files (ie. a bit too strict) and that generated files are parsable.
\end{itemize}