Down the rabbit hole

There isn’t much for documentation on that page already, but an educated
guess brought us to
the GHC module. We searched for ‘parse’ and found parseModule. So far so good, combining the information from
a tutorial from version 7.6 and what we saw in the type signatures, we
managed to call this function and get a ParsedModule.

Now we could start writing our static analysis piece, right? How
complicated can the ParsedModule be? More complicated than we
thought, as it turned out. From a ParsedModule, we got a
ParsedSource, which is just a type synonym for a Located
(HsModule RdrName). Hmm, let’s see: Located is a type
synonym for GenLocated SrcSpan and GenLocated has
the first piece of documentation: “We attach SrcSpans to lots of
things, so let’s have a datatype for it.” SrcSpan also had some
documentation, so we were able to figure out that it means “Rectangular
portion of a source file”.

Great, we know what Located and SrcSpan are,
let’s go down the other half of the rabbit hole. What is
HsModule? The documentation says “All we actually declare here
is the top-level structure for a module.”, but it does not explain why
name is a parameter. Never mind, we were looking for the
declarations in a module and specifically the left-hand side of functions.
The [LHsDecl name] part of the HsModule name seemed
promising, but what is a LHsDecl? “Left-Hand side Declaration”?
That’s exactly what we need! Oh it’s just an alias for Located
HsDecl and has nothing to do with the left-hand side of anything.
That’s anticlimactic.

This story goes on for quite a bit longer. We spend a few hours trying to
figure out how we could use the GHC API but we felt no more confident after
that than when we started, so we decided to use haskell-src-exts
instead.

Improvements

The reason why the GHC API was to confusing was twofold:

Most of the GHC API is undocumented.

Most of the names in the GHC API are abbreviations.

I had been trying to find something to do for my first GHC contribution,
so I decided to contribute documentation. In particular, I was going to add
the expansion of every abbreviation I could find in the names to their
documentation, so that the next time someone wants to write some static
analysis tool, they will not be discouraged by the API documentation.