start on some improved documentation and cleanup

* add explicit export list with section headings
* move some code and split file into logical subsections
* rename 'processFile' to more descriptive 'processHaddockDiagrams'