Improve Marmoset documentation (source comments, README)

[ulysses4ever]

@vidsinghal this is a follow-up on

• "Reusable" claim is not substantiated #7

Currently, we don't quite clear the bar for re-usable IMO: there are just not enough explanations of how the implementation works. We have time until 11:59 AM ET, February 9th, when we promised we'll deliver the updated artifact, and we could use it to improve the situation even if a bit.

Ideas for README:

• Explain how the passes fit together. Currently, we have a very short sentence about each of the passes separately but no complete story of how they work together to achieve the goal. Also, nothing about how they're hooked up with Gibbon.

• Also, individual explanations of the modules can be expanded: currently, they're too short.

Ideas for source:

• Make sure ALL functions, types and modules (see The Module Description in the Haddock docs) have haddocks. Currently, it's pretty inconsistent:

  • Gibbon/Passes/ControlFlowGraph.hs is good on function-level haddocks
  • Gibbon/Passes/DefinitionUseChains.hs is bad.
  • Please, check all of them!

• Make sure there's no commented out definitions that are leftovers from the past. E.g. I noticed ControlFlowGraph.hs starts with such comments -- it looks sloppy. There are probably more.

• Run a formatter on your modules (default fourmolu works acceptably, and you can use it from the browser vai copy-pasting if you don't want to install it). E.g.

  generateSolverEdges fundef@FunDef{funName, funBody, funTy, funArgs, funMeta} dcon fmap = 
                                                                                  let functionEdges = {-dbgTraceIt ("STARTED!")-} M.lookup funName fmap 
                                                                                  in case functionEdges of 
  
  

  Starting the first line of a function from column 80 is just unacceptable.